Skip to main content
Version: Next

Install Docker Container

One of the easiest form to use our executables for CLI usage, is by downloading and running a Docker Container. This way, the software is boundled in a container such that no installation other than docker is required.

Install docker​

First, get and install Docker following the docker installation instructions.

Get the container​

To get the container from the container registry, run the following commands in your terminal:

docker pull registry.dune-project.org/copasi/dune-copasi/dune-copasi:master
docker tag registry.dune-project.org/copasi/dune-copasi/dune-copasi:master dune-copasi

The first line downloads the container from the internet while second one creates a tagged alias named dune-copasi so that it is easier to recall.

alias collition

If you want to work with different containers from DuneCopasi, make sure that your local aliases do not collide!

Once this is done, your terminal should look something similar to this:

Pulling DuneCopasi docker image
~$ docker pull registry.dune-project.org/copasi/dune-copasi/dune-copasi:master
master: Pulling from copasi/dune-copasi/dune-copasi
09dd50cc7a64: Pull complete
820c3cdfe17d: Pull complete
c91c7d9f3fb1: Pull complete
4928c27b1e25: Pull complete
6fe40e7737d8: Pull complete
7b80474789e1: Pull complete
bd9ddc54bea9: Pull complete
Digest: sha256:56feba94d0acf8f392eb835a9c25fdbd2124a199ea55cee3ff9635a3871fd597
Status: Downloaded newer image for registry.dune-project.org/copasi/dune-copasi/dune-copasi:master
registry.dune-project.org/copasi/dune-copasi/dune-copasi:master
~$ docker tag registry.dune-project.org/copasi/dune-copasi/dune-copasi:master dune-copasi
~$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
dune-copasi master acb239d6253e 2 seconds ago 337MB
...
~$

You can check that the container is working correctly by running the --help command:

docker run dune-copasi --help

An output similar to the following should be emitted:

Command Line Interface of DuneCopasi
~$ docker run dune-copasi --help
USAGE: dune-copasi [options]

Numerical simulator for diffusion-reaction systems on single or multiple compartments

Website: <https://dune-copasi.netlify.app>

OPTIONS:

-h / --help - Display this help.
--help-full - Display this help with long descriptions.
--version - Display the version of this program.
--parser-default - Display the default parser.
--parser-list - Display the parsers available for this program.
--dimension-list - Display the grid dimensions available for this program.
--dump-config - Dumps configuration in the INI format to stdout.
--config=<string> - Specifies a config file in INI format. See Configuration Options.
--{key}={value} - Overrides key=value sections of the config file. See Configuration Options.

...
~$

Prepare a working directory​

To be able to easily share data between your operating system and the docker container, prepare a working directory with read/write rights to other users (e.g., a folder named workdir):

Creating a working directory
~$ mkdir -m o+rw workdir
~$ cd workdir
~/workdir$

This working directory will be accessible to your local text editor, paraview as well as to the dune-copasi executable within the docker container. Now, you can move or create your configuration files into it at will, for example:

Creating a configuration file
~/workdir$ echo "
[grid]
dimension = 2
...
[model.time_step_operator]
time_begin = 1
time_end = 4
" > config.ini
~/workdir$

Run the program​

At this point, you are ready to use the program through the Command Line Interface via docker. To do so, call the docker container with a configuration file config.ini:

docker run -v $PWD dune-copasi --config=config.ini

This mounts the docker container in the current directory (that's what -v $PWD means), passes the rest of the arguments to the dune-copasi executable that exists within the docker container in the same way as with the CLI usage. In this manner, the argument passed to the underlying executable is --config=config.ini while the results of the computations will be written on current directory $PWD.

When the simulation is finished finished, the last line of terminal should say whether the simulation was successful, for example:

Running DuneCopasi
~/workdir$ docker run -v $PWD dune-copasi --config=config.ini
[2024-03-21 12:38:32.479] [info] Reading configuration file '~/workdir/config.ini'
[2024-03-21 12:38:32.479] [info] Starting dune-copasi (version: 2.0.0)
[2024-03-21 12:38:32.580] [info] Axis names are set to: ["x", "y", "z"]
...
...
[2024-03-21 12:38:32.723] [info] dune-copasi successfully finished :)
~/workdir$

docker run

For more information about how to run docker containers, execute docker run --help or visit its online documentation.

Docker build​

Advanced users, who may want to make modifications the DuneCopasi code but do not to install all the dependencies may opt for a local Docker Build. For this, you must download the DuneCopasi source code, modify it as needed, and build a new local docker image as follows:

# fetch source code from git
git clone https://gitlab.dune-project.org/copasi/dune-copasi

# enter dune-copasi directory
cd dune-copasi

# checkout the branch you want to modify (e.g. latest)
git checkout latest

# modify source code at will
# ...

# build a new docker image from modified code (tag: dune-copasi)
docker build -t dune-copasi .

This will build all dune dependencies as well as the new modified version of the dune-copasi executable within the docker container. Running the program works exactly as we discussed above.