Docker / Singularity support¶
If you wish to use FORCE with docker you can do it in two ways:
- download a prebuilt image from Docker hub
- create a local build with Dockerfile
If you wish to use FORCE with Singularity, please see the instructions below.
Ready-to-go: Pull a pre-built image¶
The easiest way to use FORCE with Docker is to use a prebuilt image pulled from Docker hub with the following command:
# This takes only a few minutes docker pull \ davidfrantz/force
This downloads the latest, fully featured FORCE (3.x) on your local machine. You may want to do this regularly to always run the latest version of FORCE!
Check if this works:
docker run \ davidfrantz/force force
This displays general information about FORCE, as well as the version number.
If you want to use a specific version - or the develop branch that includes the latest cutting-edge features:
# version 3.6.5 docker run \ davidfrantz/force:3.6.5 # develop version docker run \ davidfrantz/force:dev
For developers: Local build¶
If you wish to build a Docker image instead of using the prebuilt version you can do it with the following steps from the root folder:
# This should only take a couple of minutes # The '-t' flag indicates how your local image will be named, in this case 'my-force' docker build -t my-force .
After downloading or building your own image, you can run it as a container like this:
# using the prebuilt image docker run davidfrantz/force force # using a custom built image docker run my-force force
The Docker container is isolated from your host, thus FORCE will not be able to see your local files. To share a volume, e.g. for input/output data, you can map a local folder to a folder within the container:
docker run \ -v /my/local/folder:/opt/data \ davidfrantz/force \ force-level2 /opt/data/parameters.prm
The user within the container is different than on your host. To avoid issues with file permissions, you can map your local user to the user within the container:
docker run \ -v /my/local/folder:/opt/data \ --user "$(id -u):$(id -g)" \ davidfrantz/force \ force-level2 /opt/data/parameters.prm
For the download tools, you need to share credentials between host and container.
The credentials are usually stored in
To make these files available, you need to attach the folder containing these files as a mounted volume, and set a Docker runtime environment variable pointing to that mounted folder location.
# --env sets the environment variable # this command will only print the container's FORCE_CREDENTIALS variable # should be: # FORCE_CREDENTIALS=/app/credentials docker run \ -v /my/local/folder:/opt/data \ --user "$(id -u):$(id -g)" \ --env FORCE_CREDENTIALS=/app/credentials \ -v $HOME:/app/credentials \ davidfrantz/force \ force-level1-csd -h
If you wish to enter the running container’s terminal run it with an additional
In that case you can use this terminal just as you were on a Linux machine.
If this is too long for you, you can hide all this behind an alias (or define a function).
For an alias, add a line to
$HOME/.bashrc (log off and on to take effect):
alias dforce="docker run -v /my/local/folder:/opt/data --user \"$(id -u):$(id -g)\ --env FORCE_CREDENTIALS=/app/credentials -v $HOME:/app/credentials davidfrantz/force"
After defining the alias, you can call FORCE with correct user and mounted volume - but less Docker boilerplate commands:
dforce force-level2 /opt/data/parameters.prm
The FORCE Docker images can be simply run using Singularity.
The simplest way is to directly run the Docker image:
singularity exec docker://davidfrantz/force:latest force
This will automatically pull the Docker image from Docker Hub, and convert it to a Singularity image. The image can be updated by regularly doing:
singularity pull -F docker://davidfrantz/force:latest
You can also create a local copy of the image by explicitly doing the conversion:
singularity build force.sif docker://davidfrantz/force:latest singularity exec force.sif force