Skip to main content
Version: v2.0.1

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:v2.0.1
docker tag registry.dune-project.org/copasi/dune-copasi/dune-copasi:v2.0.1 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:v2.0.1
v2.0.1: 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:v2.0.1
registry.dune-project.org/copasi/dune-copasi/dune-copasi:v2.0.1
~$ docker tag registry.dune-project.org/copasi/dune-copasi/dune-copasi:v2.0.1 dune-copasi
~$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
dune-copasi v2.0.1 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:/dunecopasi dune-copasi --config=config.ini

This mounts the docker container working directory /dunecopasi in the current directory $PWD and 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, the last line of terminal should say whether the simulation was successful, for example:

Running DuneCopasi
~/workdir$ docker run -v $PWD:/dunecopasi 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.