-
Notifications
You must be signed in to change notification settings - Fork 7
Building and running cases
If you are unfamiliar with docker, we recommend first reviewing the Docker overview wiki page and the references provided therein.
A basic template script is provided in the scripts directory of this github repo. This template includes many of the following setup examples discussed below.
Currently the docker images only support the use of the gcc compilers. As such the user should make sure to use --compiler=gnu option for the create_newcase call.
When calling create_newcase in your script, the --mach option should be set to docker:
./create_newcase --mach=docker ...
The config_compiler.xml and config_machine.xml files have a docker entry to tell the host land model where to find the necessary libraries and default settings for a case run in the container.
Evaluating the machine environement variable HOSTNAME is a common method to provide build script portability between machines:
./create_newcase --mach=${HOSTNAME} ...
If your script uses this method, you must include the --hostname option and set it to docker when running a container:
docker run -ti --rm --hostname docker ngeetropic/fates-ctsm-gcc650:latest
The fates-hlm docker images provide four empty directories by default for the user to interface with: /inputdata, /output, /scripts, and /baselines. They are located on the same directory level as the host land model in the root directory of the container:
I have no name!@docker:/$ ls -ltr
total 84
drwxr-xr-x 2 root root 4096 Jun 14 2018 boot
drwxr-xr-x 1 root root 4096 Apr 22 00:00 var
drwxr-xr-x 1 root root 4096 Apr 22 00:00 usr
drwxr-xr-x 2 root root 4096 Apr 22 00:00 srv
drwxr-xr-x 2 root root 4096 Apr 22 00:00 sbin
drwxr-xr-x 4 root root 4096 Apr 22 00:00 run
drwxr-xr-x 2 root root 4096 Apr 22 00:00 opt
drwxr-xr-x 2 root root 4096 Apr 22 00:00 mnt
drwxr-xr-x 2 root root 4096 Apr 22 00:00 media
drwxr-xr-x 2 root root 4096 Apr 22 00:00 lib64
drwxr-xr-x 1 root root 4096 Apr 23 00:57 lib
drwx------ 1 root root 4096 Apr 25 01:15 root
drwxr-xr-x 1 root root 4096 May 16 01:09 bin
drwxrwxrwt 1 root root 4096 May 16 02:25 tmp
drwxr-xr-x 1 root root 4096 Sep 10 00:02 home
drwxr-xr-x 2 root root 4096 Sep 10 00:02 scripts
drwxr-xr-x 2 root root 4096 Sep 10 00:02 output
drwxr-xr-x 2 root root 4096 Sep 10 00:02 inputdata
drwxr-xr-x 2 root root 4096 Sep 10 00:02 baselines
drwxr-xr-x 14 root root 4096 Sep 10 00:02 CTSM
drwxr-xr-x 1 root root 4096 Sep 18 22:24 etc
dr-xr-xr-x 464 root root 0 Sep 18 22:24 proc
dr-xr-xr-x 13 root root 0 Sep 18 22:24 sys
drwxr-xr-x 5 root root 360 Sep 18 22:24 dev
These are provided as the default interface points for passing data back and forth between the container and the user account. Of these directories, /inputdata, /output, and /baselines have been defined in the cime configuration files as the default locations for <DIN_LOC_ROOT>, <CIME_OUTPUT_ROOT>, and <BASELINE_ROOT>. Reference information for machine definitions variables can be found in the CIME documentation.
To interface with these directories the user must provide access to account directories external to the container for reading and writing data as necessary. This is facilitated by the use of docker volume mounts. An example of using the default mount points is below:
docker run -ti --hostname=docker --u $(id -u):$(id -g) \
-v <external-inputdata-directory>:/inputdata \
-v <external-output-scratch-directory>:/output \
-v <external-baselines-directory>:/baselines \
ngeetropics\fates-ctsm-gcc650:latest
Note the use of the -u option. As discussed in the docker overview wiki page, this is necessary to use in conjunction with the -v option to provide the files created by the container the same user id and group id as your account.
Also note that if the script call is not generating or comparing against baselines, the mounting of /baselines is not necessary
Alternatively, Docker can create directories within the container on the fly the user does not wish to use the defaults. To do so the user must make sure to use the ./xmlchange command in your script to override the cime configuration defaults as well as set the correct output directory location for create_newcase:
- Override defaults in script example:
# Set the correct output directory for create_newcase ./create_newcase --case=<container-output-directory>/<new-case-name> ... ... cd <container-output-directory>/<new-case-name> # Override the .cime configuration default to match the argument for dir locations ./xmlchange CIME_OUTPUT_ROOT=<container-output-directory> ./xmlchange DIN_LOC_ROOT=<container-inputdata-directory> ./xmlchange DIN_LOC_ROOT_CLMFORC=<container-inputdata-directory>/atm/datm7- See the corresponding template script section for a similar implementation
- Corresponding
docker runcommand that matches volume mount directories specified in the scriptdocker run -ti --hostname=docker --u $(id -u):$(id -g) \ -v <external-inputdata-directory>:<container-inputdata-directory> \ -v <external-output-scratch-directory>:<container-output-directory> \ <docker-image>:<tag> \ /scripts/<build-script> <optional-script-inputs>
Although docker can be used interctively using the -ti option with docker run, enabling the user to setup and run a case within the container, it is possible to call the necessary scripts and commands directly from docker run command external from the container:
-
Calling build script
docker run -ti --hostname=docker --u $(id -u):$(id -g) \ -v <input-data-directory>:/data \ -v <output-scratch-directory>:/output \ -v <scripts-directory>:/scripts \ <docker-image>:<tag> \ /scripts/<build-script> <optional-script-inputs> -
Run case
docker run -ti --hostname=docker --u $(id -u):$(id -g) \ -v <input-data-directory>:/data \ -v <output-scratch-directory>:/output \ <docker-image>:<tag> \ /bin/sh -c 'cd /output/<case-directory> && ./case.submit'