fre.make.create_docker_script module

Create_docker_script contains one method called dockerfile_create to to generate a Dockerfile and an accompanying createContainer.sh script to build container images.

A two-stage build is recommended:

  1. Build stage — starts from the base container image (containerBase in platforms.yaml), copies in the checkout.sh and Makefile that were staged under tmp/[platform]/ by fre make checkout-script and fre make makefile, runs mkmf and make to compile the model.

  2. Runtime stage — copies the compiled executable and its runtime dependencies into a leaner second base image (containerBase2 in platforms.yaml), and removes the Intel compiler used in the Build stage.

createContainer.sh builds the container image and, unless –no-format-transfer is specified, converts it to a Singularity Image File (.sif) that can be launched with Singularity/Apptainer on HPC systems.

Note

Once a container image is built, the source code and compiled executable inside it cannot be modified. To incorporate source changes, re-run fre make all (or the individual sub-commands) and rebuild the image.

fre.make.create_docker_script.dockerfile_create(yamlfile: str, platform: tuple[str], target: tuple[str], execute: bool = False, no_format_transfer: bool = False)

Dockerfile_create generates a Dockerfile and createContainer.sh for each container platform/target combination and optionally executes the build script to produce a container image.

fre make checkout-script and fre make makefile should be invoked beforehand to stage the checkout.sh script and Makefile in tmp/[platform-name]/.

Parameters:

  • yamlfile (str) – is the path to the model YAML file (e.g. am5.yaml).

  • platform (tuple[str]) – is one or more FRE platform strings as defined in platforms.yaml. Only container platforms (container: True) are processed; bare-metal platforms are skipped.

  • target (tuple[str]) – is one or more mkmf target strings (e.g. prod-openmp, repro-openmp, debug-openmp). One Dockerfile is generated per platform/target pair.

  • execute (bool) – is a flag where if True, run createContainer.sh immediately after generation to build the container image. Defaults to False.

  • no_format_transfer (bool) – is a flag where if True, skip the OCI-to-Singularity (.sif) format conversion step in createContainer.sh. Defaults to False.

Raises:

ValueError – If a specified platform does not exist in platforms.yaml.

Note

If building the container image on GFDL’s RDHPCS GAEA with the Podman container engine, please submit a GFDL servicedesk ticket to request Podman access before running this command.