Dockerfiles

Two configurations are possible depending on how OpenIFS might be used in a container:

The

Dockerfiles

The Dockerfile describes the build process of the container image. Examples for several of these files are provided in the OpenIFS git repositoryin OpenIFS from version 43r3v1 onwards. The naming convention for Dockerfiles is as such:

Example:    Dockerfile.oifs40r1v2.41537oifs43r3v1.user.x86_64.bldbld  will generate an image of the OpenIFS 43r3v1 release.

Example Build Process

The following This section describes the build generation process of a container image from the Dockerfile. You need the following files in your build directory:.

1. Start by navigating to the docker directory in the OpenIFS distribution:

% cd tools/docker

2. Make a copy of one of the Dockerfile templates that can be found in this directory. There are two versions:

% ls Dockerfile*
Dockerfile.oifs43r3v1

.root.x86_64.

bld	Dockerfile.

oifs43r3v1.

user.x86_64.

bld

% cp Dockerfile.oifs43r3v1.user.x86_64.bld  Dockerfile

The Dockerfile can be obtained from the git repository. As described through the naming convention it will generate an image of OpenIFS 40r1 version 2. The partial git hash relates the Dockerfile (and image) to a specific git commit in the OpenIFS repository (in this case it relates to 415374d which is tagged as model release v2 ). The note 'root' indicates that when the image is loaded as a container the user will have root privileges. This will allow us to explore the directory structure of the container image. For convenience it is recommended to create a symbolic link to the generic name Dockerfile.OpenIFS is installed into a system directory /usr/local whereas the 'user' version installs into the user's account. Both Dockerfiles create a user called 'oifs'.

Which you choose depends on your application. The 'root' version might be more suited to a training workshop for example.  We'll use the 'user' version in this example.

3. Put a copy of the OpenIFS distribution tarfile as downloaded into the same directory as the Dockerfile.

You should have these files in your build directory (your version numbers may be different):

-rw-r--r-- 1 glenn staff 4255 6 May 17:35 Dockerfile
-rw-r--r-- 1 glenn staff 30611901 6 May 18:13 oifs43r3v1.tar.gz

4. Build the OpenIFS Docker imageThe tar archive oifs40r1v2.41537.tar.gz is created from the model sources after they have been checked out from the git repository (again the partial commit is specified). The Dockerfile will expect the tar archive in the same directory and the file name is specified.

The following command builds the image oifs40r1v2oifs43r3v1.415374d.root. The generic command is  docker build -t <image_name>  however user. Change 'user' to 'root' if building the other variant.

% docker build -t oifs43r3v1.user   .         #  note the trailing '.' to build in the current dir

docker

 build -t

 oifs43r3v1.user --build-arg http_proxy="$http_proxy" --build-arg ftp_proxy="$ftp_proxy" --build-arg https_proxy="$https_proxy" --build-arg no_proxy="$no_proxy"  .

This starts runs the generation build process of the image which contains the minimum of software that is required to run OpenIFS.

The image is based on a Ubuntu Linux LTS version and in a first step . After downloading the base Ubuntu image, the Dockerfile executes the following steps: the necessary developer tools are installed (e.g. GNU compiler, MPI and maths libraries). Afterwards ; the ecCodes library is obtained via download from the web downloaded and compiled with minimum settings. Then ; the OpenIFS sources are added unpacked from the tar archive, required environment variables are set and the model binaries are compiled. During a The last step various sets file permissions are set and the model executable is moved to a globally accessible an install location.

At the end of the build process the successful image creation is shown as: 
Successfully tagged oifs40r1v2oifs43r3v1.415374d.rootuser:latest

Running the docker image

We can verify Now we can verify the that the image is available and load it into a container using the  docker run  command:

% docker images
REPOSITORY             TAG                 IMAGE ID            CREATED             SIZE
oifs43r3v1.user        latest              982f6e82bb93        39 minutes ago      873MB
ubuntu                 latest              72300a873c2c        13 days ago         64.2MB

% docker run -it oifs43r3v1.user
oifs@40a923f11202:~$

Our command line prompt has changed as we are now the user 'rootoifs' inside the container.

A file directory listing shows the directory structure inside the container. 

following structure (your version numbers may be different): 

oifs@40a923f11202:~$ ls
oifs43r3v1
oifs@40a923f11202:~$ ls oifs43r3v1
CHANGES  COPYING  NOTICE  READMEs  examples  make                   oifs-config.sh  t21test       tools
CITE     LICENSE  README  bin      fcm       oifs-config.editme.sh  src             t21test_xios
oifs@40a923f11202:~$ 

The compiled model executables can be found in and can be moved to another install location:

oifs@40a923f11202:~$ ls oifs43r3v1/make/gnu-opt/oifs/bin
getres.exe  grib_set_vtable.exe  master.exe  spinterp.exe  timeint.exe  vod2uv.exe
gptosp.exe  intsst.exe           rgrid.exe   sptogp.exe    uvtovod.exe

The The OpenIFS model is installed in /oifs. The ecCodes library is found in its default destination under /usr/local/lib. 

With the command 'exit' the container is removed and all created or changed files in the container are lost. The next section will show how results can be retained and OpenIFS experiments can be run using a container.

Running

OpenIFS experiments in a

In this section we describe a method how the containerised version of OpenIFS can be used to run a case study on the user's workstation. 

(tbc...)

container

Due to the temporary nature of containers all model results that are created in an experiment need to be stored outside the container. One possible method is to mount an external experiment directory inside the container. Data written to the mounted directory will be retained once the container is removed.

Assume an experiment directory at /scratch/user/exp/.

This experiment directory is mounted to the container when it is invoked:

docker run -v /scratch/user/exp:/home/oifs/exp:rw -it oifs43r3v1.user

A mount of the experiment directory can be found inside the container in sub-directory /exp with read and write permissions.

In order to mount the external experiment directory successfully, all the files or sub-directories need to have full read-write-executable access:  chmod -R 777 /scratch/user/exp

All the files in the mounted directory that were newly created or modified are owned by the container user, seen from outside the container their file ownership will be different. 

Invoking the container from the OpenIFS run script

An alternative method of using OpenIFS in a container consists of including the docker call inside the oifs_run script, replacing the execution of the model binary with mpirun.

This method is only suitable for running the model interactively (i.e. no batch job submission). The modification in the script is as follows:

  When using this method the Docker container environment remains "concealed" from the model user and requires no further interaction with it.

Batch Job Submission

The use of Docker containers when running OpenIFS on HPC facilities has been tested successfully and with good scalability on the Piz Daint Cray XC50 at the Swiss National Supercomputing Centre in December 2019 using local computing support. At present we do not yet offer this capability at ECMWF.

Crib Sheet: Important Docker commands

This section contains a list of frequently used Docker commands.

Start the Docker deamon on your machine (ECMWFif not already running):

which is actually:    sudo /usr/bin/systemctl status docker

ECMWF users may need to contact servicedesk to request permission to run Docker.

Which images are on my machine:

Which containers are running:

Build docker image:

Run docker images in container:

Do this first:   docker login eccr.ecmwf.int

The build command below makes an image that can be pushed to harbor:   docker build -t eccr.ecmwf.int/openifs/oifs:0.0.1 -f --build-arg http_proxy="$http_proxy" --build-arg ftp_proxy="$ftp_proxy" --build-arg https_proxy="$https_proxy" --build-arg no_proxy="$no_proxy"

Then push it to harbor, manually specifying version number.  Careful: Existing version numbers are overwritten!     docker push eccr.ecmwf.int/openifs/oifs:0.0.1