... | ... | @@ -10,91 +10,130 @@ _Precompiled packages (Docker)_ |
|
|
|
|
|
## ![>](/icons/docker.svg) Docker
|
|
|
|
|
|
OpenCFD Ltd. uses [Docker Hub](https://hub.docker.com/) to distribute
|
|
|
pre-compiled versions of OpenFOAM for Linux, Mac OS X and Windows,
|
|
|
including a complete development environment.
|
|
|
OpenCFD Ltd. uses [Docker Hub][dockerhub-opencfd] to distribute
|
|
|
[_container images_](https://en.wikipedia.org/wiki/OS-level_virtualization)
|
|
|
with pre-packaged, pre-compiled versions of [OpenFOAM](www.openfoam.com)
|
|
|
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.
|
|
|
|
|
|
Docker containers enable binaries compiled on a given Linux environment to
|
|
|
be run on other platforms without any performance degradation. Docker also
|
|
|
operates on Windows and Mac OS X wrapped in a light-weight Virtual Box.
|
|
|
### Installing Docker
|
|
|
|
|
|
An image of OpenFOAM contains binaries and source code. The Docker environment provides:
|
|
|
- A complete development environment to compile local modifications and create executables.
|
|
|
- consistent behaviour of the OpenFOAM across all platforms
|
|
|
- Get and install docker: https://docs.docker.com/engine/install/
|
|
|
- Setup docker user: https://docs.docker.com/engine/install/linux-postinstall/
|
|
|
|
|
|
Check if your (Linux or Windows or Mac OS X) system is supported by visiting
|
|
|
https://docs.docker.com/engine/installation/
|
|
|
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 |
|
|
|
|
|
|
### Installing Docker
|
|
|
|
|
|
Docker is available in a Community Edition (CE) and an Enterprise Edition
|
|
|
(EE). For installing and running the OpenFOAM image, the Community Edition is
|
|
|
sufficient.
|
|
|
Please see: https://docs.docker.com/engine/installation/
|
|
|
## About the image
|
|
|
|
|
|
### Installing and running OpenFOAM
|
|
|
The current image uses the latest Ubuntu LTS version.
|
|
|
If you wish to install any additional tools in your docker container,
|
|
|
start it as usual via the [_openfoam-docker_][run-script] script.
|
|
|
Additional information about _sudo_ is available within the container
|
|
|
- follow the welcome banner for _local help_.
|
|
|
|
|
|
- Make sure the user is in the _docker_ group.
|
|
|
This can be checked with
|
|
|
```
|
|
|
$ id
|
|
|
```
|
|
|
The list of groups should include _docker_.
|
|
|
- Make sure the Docker daemon is running:
|
|
|
```
|
|
|
$ docker info
|
|
|
```
|
|
|
- Download the following scripts from the release instructions and put them
|
|
|
in a local directory (_eg_, your home directory)
|
|
|
- [installOpenFOAM][install-script]
|
|
|
- [startOpenFOAM][start-script]
|
|
|
- Make both scripts executable:
|
|
|
```
|
|
|
$ chmod +x installOpenFOAM
|
|
|
$ chmod +x startOpenFOAM
|
|
|
```
|
|
|
- Download and create the Docker container for OpenFOAM by executing the
|
|
|
first script:
|
|
|
```
|
|
|
$ ./installOpenFOAM
|
|
|
```
|
|
|
This only needs to be done once per login. The first invocation will
|
|
|
download the whole OpenFOAM installation so might take some time to finish.
|
|
|
Future invocations will only take a few seconds.
|
|
|
- Start the Docker container with the second script:
|
|
|
|
|
|
## Running OpenFOAM in a container
|
|
|
|
|
|
- Download the [openfoam-docker][run-script] 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,
|
|
|
```
|
|
|
$ ./startOpenFOAM
|
|
|
$ chmod +x openfoam-docker
|
|
|
$ ln -sf openfoam-docker openfoam2106-run
|
|
|
```
|
|
|
- This will open a new shell with the OpenFOAM environment fully installed
|
|
|
and ready to use. For example,
|
|
|
- Verify that the script (or link) can be executed,
|
|
|
and take a look at some of the available options:
|
|
|
```
|
|
|
mkdir -p $FOAM_RUN
|
|
|
run
|
|
|
cp -p $FOAM_TUTORIALS/incompressible/icoFoam/cavity/cavity .
|
|
|
cd cavity
|
|
|
blockMesh
|
|
|
icoFoam
|
|
|
$ openfoam-docker -help
|
|
|
```
|
|
|
- All user files inside the Docker environment are available on the host inside
|
|
|
the home directory.
|
|
|
|
|
|
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][dockerhub-opencfd] 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
|
|
|
|
|
|
- <em>Is there any performance degradation when running via Docker?</em><br/>
|
|
|
Docker should run as fast as natively compiled code.
|
|
|
On Windows and Mac OS X there may be a slight performance penalty
|
|
|
associated with I/O.
|
|
|
- <em>How do I check if the OpenFOAM image has been downloaded correctly?</em><br/>
|
|
|
- _Is there any performance degradation when running via Docker?_<br/>
|
|
|
- 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?_<br/>
|
|
|
Type the command
|
|
|
```
|
|
|
$ docker images
|
|
|
```
|
|
|
to show the images available in Docker environment. For example,
|
|
|
```
|
|
|
REPOSITORY TAG IMAGE ID CREATED SIZE
|
|
|
openfoamplus/of_v2006_centos73 latest f37ab3b17c2d 2 months ago 2.98GB
|
|
|
REPOSITORY TAG IMAGE ID CREATED SIZE
|
|
|
opencfd/openfoam2012-run latest xxxxxxxxxxxx N days ago 628MB
|
|
|
opencfd/openfoam2012-dev latest xxxxxxxxxxxx N days ago 1.35GB
|
|
|
...
|
|
|
```
|
|
|
If you receive an error message about not being able to contact the Docker
|
... | ... | @@ -122,31 +161,16 @@ Please see: https://docs.docker.com/engine/installation/ |
|
|
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!)
|
|
|
- <em>What does installOpenFOAM do?</em><br/>
|
|
|
It downloads the OpenFOAM image from the Docker Hub and creates a
|
|
|
specialized container. This container
|
|
|
- mounts the home directory of the user with read/write access
|
|
|
- optionally channels the graphics
|
|
|
- sets up the OpenFOAM environment.
|
|
|
|
|
|
- <em>I still have questions...</em><br/>
|
|
|
The Docker route is being continually refined. It you have comments/tips
|
|
|
please mail them to: `docker (at) opencfd.co.uk`
|
|
|
|
|
|
|
|
|
## About the image
|
|
|
|
|
|
The current image was created from CentOS 7.3.
|
|
|
If you wish to install any additional tools in your docker container,
|
|
|
start it as usual via the _startOpenFOAM_ script, and login as root,
|
|
|
i.e. `su root` with the password `openfoam`
|
|
|
|
|
|
Please note: the image is centos-based and you will need to use the `yum`
|
|
|
command to install packages.
|
|
|
|
|
|
- <em>Program XYZ is missing in the container, how do I install it?</em><br/>
|
|
|
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.
|
|
|
|
|
|
---
|
|
|
Copyright (C) 2020-2021 OpenCFD Ltd.
|
|
|
|
|
|
[install-script]: https://sourceforge.net/projects/openfoam/files/v2006/installOpenFOAM
|
|
|
[start-script]: https://sourceforge.net/projects/openfoam/files/v2006/startOpenFOAM |
|
|
[dockerhub-opencfd]: https://hub.docker.com/u/opencfd
|
|
|
[run-script]: /packaging/docker/openfoam-docker |