docker

Precompiled packages (Docker)

Docker
- Installing Docker
About the image
Running OpenFOAM in a container
- Running interactively
- Running non-interactively
Frequently Asked Questions about Docker

Docker

OpenCFD Ltd. uses Docker Hub to distribute container images with pre-packaged, pre-compiled versions of OpenFOAM for Linux, Mac OSX and Windows. There are a variety of image flavours available:

-run : a small-footprint runtime-only image
-dev : runtime with OpenFOAM development environment
-default : just-give-me-everything image

Containerization allow binaries compiled on a given Linux platform to run on other platforms (Linux, Windows, OSX) without significant degradation in performance. For data centres, containers are an attractive means of encapsulating applications.

Installing Docker

Get and install docker: https://docs.docker.com/engine/install/
Setup docker user: https://docs.docker.com/engine/install/linux-postinstall/

Some possible commands after installing:

Command	Comment
`$ id`	Check that the user belongs to the docker group
`$ sudo /usr/sbin/usermod -aG docker $(whoami)`	Add current user to the docker group
`$ docker info`	Verify the docker daemon is actually running
`$ docker images`	List local images

About the image

The current images uses the latest Ubuntu LTS version and are created following recipes similar or identical to those given in the corresponding packaging/containers files.

If you need to install any additional tools temporarily in your docker container, start it as usual via the openfoam-docker script. Additional information about sudo is available within the container (follow the welcome banner for local help).
If you need install any tools permanently in your docker image, use one of the docker files from the packaging/containers repository as a template for creating your own custom image.

Running OpenFOAM in a container

Download the openfoam-docker run script and place it somewhere convenient in your path (eg, $HOME/bin etc)
Make the script executable, and set links to some preferred OpenFOAM versions and image flavours. For example,
```
$ chmod +x openfoam-docker
$ ln -sf openfoam-docker openfoam2106-run
```
Verify that the script (or link) can be executed, and take a look at some of the available options:
```
$ openfoam-docker -help
```

This downloaded run script is the recommended means to enter the OpenFOAM image. Assuming that the corresponding link has been made, calling it without any arguments will bind in the local directory and start the image with an OpenFOAM environment. Eg,

$ openfoam2106-run

This will open an interactive shell with the OpenFOAM environment active, with the current local directory mounted within the container.

Note: The first time the script is executed, it will take a bit longer to start, since it also needs to download the Docker Hub image.

Running interactively

Running an interactive shell with the OpenFOAM environment active is the default behaviour for the image and run-script.

For example,

$ openfoam-docker -2012

Running non-interactively

It is also possible to use the image in batch mode. The key is to ensure that the run-script understands where the commands begin. For this, the standard -- or - separator can be used. For potentially more readable input, a single isolated / also works.

For example,

$ openfoam-docker -2012 -- blockMesh -help

It is also possible to use the run-script to run shell scripts. For example,

$ openfoam-docker -2012 -c './Allrun'

Note that the entry point within the image itself also has some option handling. For example,

$ openfoam-docker -2012 -- -help

Frequently Asked Questions about Docker

Is there any performance degradation when running via Docker?
- On Linux, the docker should run as quickly natively hosted code.
- On Windows and OSX there is a slight performance penalty, largely related to I/O.
How do I check if the OpenFOAM image has been downloaded correctly?
Type the command
```
$ docker images
```
to show the images available in Docker environment. For example,
```
REPOSITORY                 TAG      IMAGE ID       CREATED      SIZE
opencfd/openfoam2106-run   latest   xxxxxxxxxxxx   N days ago   640MB
opencfd/openfoam2106-dev   latest   xxxxxxxxxxxx   N days ago   1.38GB
...
```
If you receive an error message about not being able to contact the Docker daemon check that:
- the Docker daemon is started at boot time
- the user account is in the docker group (see output from the id command)
Where are my files?
The user files inside Docker are visible (ie, mounted) in your home area and can be operated on just like any other file.
Why doesn't paraFoam display?
Make sure that your machine's software is fully up-to-date. See if you can start a simple X-windows, non-graphics program (for example, xterm). If this does not come up there may be a problem with the xhost access to the host screen. This is one of the steps inside the startOpenFOAM script. An alternative remedy is to install the native ParaView version for your system, and use the built-in OpenFOAM reader and/or OpenFOAM data conversion tools such as foamToVTK.
How do I run parallel?
Same as any other OpenFOAM installation, e.g.: mpirun -np 2 icoFoam -parallel
How do I run parallel on multiple computers?
This is not trivial inside the Docker environment. Also you might want to include optimised communication libraries (MPI) so it probably makes more sense to perform a native compilation
How do I compile code?
The Docker environment contains a full OpenFOAM development environment so all wmake, wclean etc. commands work (it is running the actual environment OpenFOAM was compiled in!)
Program XYZ is missing in the container, how do I install it?
Follow the information in the welcome banner (local help) for managing sudo. Any programs installed within the container will disappear after the container is destroyed. If you have programs that you believe absolutely must be installed (but maybe only for you), you can simply create your own docker images on top of those provided from OpenCFD.