Using pre-built deal.II Docker Containers

[anicusan]

Hello again for today's fourth discussion topic! Apologies to lethe devs' inboxes...

Compiling deal.II with its exact dependencies - which have their own dependencies (Trilinos and PETSc were fun...) - is no mean feat; it can be a bit daunting when only a couple of tests fail 4 hours into the compilation procedure.

Thankfully, the deal.II dev heroes also maintain some Docker Hub images containing pre-built deal.II libraries in a Ubuntu environment. For those unfamiliar with Docker, it allows the creation of completely isolated environments, most often pre-configured for specific apps; it is almost like a virtual machine, but running natively on your current OS (the technical term is OS-level virtualization, rather than hardware-level) - so scientific programs shouldn't have any degradation in performance.

Sometimes it's easier to effectively set up a completely new OS than compile millions of lines of C++...

0. TL;DR

Get Docker, then in some directory run:

local:~$ mkdir lethe-simulations && cd lethe-simulations
local:~/lethe-simulations$ docker run -it --name lethe-container -v $(pwd):/home/docker-host dealii/dealii:master-focal
To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.

dealii@2e92a38a6223:~$ cd /home/docker-host/
dealii@2e92a38a6223:/home/docker-host/$ # compile lethe and run simulations here

And do the final lethe compilation step.
This starts a new docker container with an interactive terminal (-it) named lethe-container, mounting the current directory on your machine to /home/docker-host. Inside the container, run any simulations in the /home/docker-host directory to save them locally too.

Exit the docker container with ctrl-d; run docker ps -a to see the current containers on your machine - you'll see the lethe-container. Restart your container and attach to its terminal with:

docker start lethe-container && docker attach lethe-container

Have fun.

1. Get Docker

First, install Docker; complete instructions for Windows, Mac or Linux can be found here; this should be a relatively quick step.

2. Launch a deal.II Container

Some Docker basics:

• A Docker image is a "frozen", shareable environment - e.g. a Ubuntu terminal with pre-installed deal.II and its dependencies.
• You can launch a container running that specific image, in which you can e.g. compile lethe and run simulations. Indeed, you can run multiple separate containers of the same image.

In your terminal, you can then run:

docker run -it --name lethe-container dealii/dealii:master-focal

This starts a new container with an interactive terminal (-it) running the dealii/dealii:master-focal image (here are all the deal.II images) named lethe-container. Press ctrl-d to exit the container.

To see your current docker containers, run:

docker ps -a

CONTAINER ID   IMAGE                        COMMAND   CREATED          STATUS                      PORTS     NAMES
e3a7f71639f6   dealii/dealii:master-focal   "bash"    14 minutes ago   Exited (0) 35 seconds ago             lethe-container

This container saved your changes. You can restart and attach to the container's terminal by running:

docker start lethe-container && docker attach lethe-container

If you want to, you can remove the container with docker rm lethe-container; you'll start a new fresh container by running the docker run... command above.

However, any files saved in the container are only accessible inside it, and are lost when removing the container. For simulations on the other hand, we want their outputs to be saved and accessible on the local machine (e.g. to post-process them); for this, we will mount a directory from the local machine to the container with -v LOCAL_DIR:CONTAINER_DIR. While in the container, anything you save to CONTAINER_DIR will be accessible on your local machine in LOCAL_DIR.

For example, on your local machine:

local:~$ mkdir ~/lethe-simulations
local:~$ cd ~/lethe-simulations
local:~/lethe-simulations$ ls

local$ docker run -it --name lethe-container -v $(pwd):/home/docker-host dealii/dealii:master-focal
To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.

dealii@2e92a38a6223:~$ cd /home/docker-host/
dealii@2e92a38a6223:/home/docker-host$ echo "Hello lethe!" > somefile.txt
dealii@2e92a38a6223:/home/docker-host$ exit

local:~/lethe-simulations$ ls
somefile.txt

That's all the Docker-specific tutorial! Launch your container running a deal.II image, go to /home/docker-host to save your changes locally too, download lethe, compile it, and run your simulations there.

3. Saving Docker Commands in a Bash Script

We can add all the commands above, plus some comments and helpful messages to a single shell script named docker_lethe.sh:

#!/bin/sh

# Launch a persistent docker container from a given image, automatically re-attaching to it on
# future runs.
#
# The current local directory is mounted in /home/docker-host within the container; run any
# simulations there to save results on the local machine's current directory.

DOCKER_IMAGE='dealii/dealii:master-focal'
DOCKER_CONTAINER="$USER-${DOCKER_IMAGE##*/}"        # Remove repository prefix
DOCKER_CONTAINER=${DOCKER_CONTAINER/:/-}            # Replace : with -

HOST_DIR=$(pwd)
REMOTE_DIR="/home/docker-host"


printf "Image:     ${DOCKER_IMAGE}\nContainer: ${DOCKER_CONTAINER}\n\n"


# If a container with this name already exists, re-attach to it
if [ "$(docker ps -q -af name=${DOCKER_CONTAINER})" ]
then
    printf "Found previous container with same name; starting and attaching...\n\n"
    docker start ${DOCKER_CONTAINER}
    docker attach ${DOCKER_CONTAINER}
else
    printf "Launching new container...\n\n"
    docker run -it \
        --name $DOCKER_CONTAINER \
        -v $HOST_DIR:$REMOTE_DIR \
        $DOCKER_IMAGE
fi

Then just execute the shell script:

local:~/lethe-simulations$ sh docker_lethe.sh

Final Notes

If the lethe developers believe this tutorial is useful, I'd be more than happy to submit a pull request to the lethe wiki. If more brevity would be useful (I didn't set out to write a Docker tutorial too but hey ho...), perhaps just the last script could be included in the lethe repository, so that first-time users can just copy the file to a separate directory, run it and have the deal.II environment immediately ready.

Best wishes,
Leonard

[blaisb]

Dear Leonard,
That's an amazing tutorial. These docker image are indeed quite nifty (we use them all over the place in our CI).
We have a new Sphinx documentat that is currently being deployed. The syntax (RST) is quite simple to use and it is similar to Markdown.
Would you be willing to make a PR that includes these docker instructions within the new documentation?

The contribute page of the documentation has all the necessary information on how to compile the doc:
https://lethe-cfd.github.io/lethe/contributing.html

The doc files are now housed directly in the repository:
https://github.com/lethe-cfd/lethe/tree/master/doc

Feel free to add a new page in the documentation related to deploying on Docker. This could be useful for so many others :).

[blaisb]

This tutorial is now part of the Lethe documentation :)