Quick start with Docker#

There are different options to deploy this framework. For a quick start and versatile development environment that works on many platforms – from your local laptop to large scale high performance computers – we rely on Docker.

Why Docker?#

Configuring a workstation directly and working on this machine has disadvantages that become problematic over time.

Lock-in: The exact configuration cannot be reproduced (easily), so there’s no other option than to keep developing on that single workstation, even if there are better options (e.g. a second faster or less occupied workstation).
Reproducibility: Since the configuration is not documented, reproducing a simulation is hard if the configuration has been changed.
Updates: It is difficult to update the environment (e.g. libraries), since older versions of the code may depend on older versions of the library. This leads to broken builds without changed code for older versions of the code.
Permissions: Installing libraries, even if they are available via apt-get, requires support by an administrator. It is difficult to quickly test a library.
Testability: Automatic tools that check the code also need to run on this workstation to verify that it works.

This leads to a situation where it’s hard to improve both the environment and the code.

The benefit of using Docker is to have a development environment that can be shared between developers, can be created on all platforms, and can be modified easily. The commands that define the environment are in a single short file, the Dockerfile. This Dockerfile is versioned together with the code.

Requirements#

Docker supports Linux, MacOS, and Windows hosts. In the following, one of the following operating systems is required:

Ubuntu 20.04 Focal
Windows 10/11
MacOS 12 Monterey

Tutorial#

The following tutorial guides you through a quick way to set up a development environment on your machine using Docker and Visual Studio Code.

Install Git by following the instructions available at git-scm.com (use the default settings on Windows).
Install Docker by following the instructions available at docker.com.

If you are using Linux then install rootless Docker via the instructions and activate it using:
```
docker context use rootless
```
If you are on Linux, install Docker Compose by following the instructions available at docker.com (Docker Desktop for Windows/Mac already comes with Docker Compose). In particular, the package docker-compose can also be installed via pip:
```
pip3 install docker-compose
```
Install Visual Studio Code by following the instructions available at visualstudio.com. In addition, install the following Visual Studio code extensions (by Microsoft):
Click the “Clone” button on the GitLab website of the repository and select “Visual Studio Code” in the menu. After you’ve chosen a target directory a new Visual Studio Code window should open automatically. Confirm opening the new folder when VS Code asks you to.
VS Code shows a dialog box informing you that the repository provides a “Dev Container” configuration. Start this container via the button “Reopen in Container”. This can take a few minutes to complete.
Click the CMake icon in the menu on the left, and click the “Configure all Projects” button on the top of the CMake pane.
Build the project by clicking “Build all Projects” on the top of the CMake pane.

Execute an interactive bash shell in the container#

After starting the container as described above, you can also jump right into the container from your terminal (outside of VS Code) by executing an interactive bash shell. The command is:

docker exec -it <container name> bash

If you do not know your <container name>, you may always look it up with the following command:

docker ps