... | ... | @@ -4,9 +4,12 @@ |
|
|
[![packages](/icons/package.svg "packages")](/precompiled)
|
|
|
|
|
|
_Precompiled packages (Docker)_ <br>
|
|
|
***Quick-start***: <br>
|
|
|
|
|
|
**Quick-start:** <br>
|
|
|
If docker is already installed and setup, simply download the
|
|
|
[_openfoam-docker_][run-script] and run it.
|
|
|
[_openfoam-docker_ script][run-script] and run it. Post-process with
|
|
|
the [native ParaView][link paraview], for better performance and easy
|
|
|
configuration. [Do _not_ bother with the paraFoam script][faq paraview].
|
|
|
|
|
|
----
|
|
|
|
... | ... | @@ -24,27 +27,12 @@ There are a variety of image flavours available: |
|
|
- `-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 |
|
|
|
|
|
|
Containers allow binaries compiled on a given 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.
|
|
|
|
|
|
## About the image
|
|
|
### 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
|
... | ... | @@ -57,7 +45,7 @@ corresponding [packaging/containers][packaging-containers] files. |
|
|
- If you need install any tools _permanently_ in your docker image,
|
|
|
use one of the docker files from the [packaging/containers
|
|
|
repository][packaging-containers] as a template for creating your
|
|
|
own custom image.
|
|
|
own custom images.
|
|
|
|
|
|
|
|
|
## Running OpenFOAM in a container
|
... | ... | @@ -68,21 +56,28 @@ corresponding [packaging/containers][packaging-containers] files. |
|
|
OpenFOAM versions and image _flavours_. For example,
|
|
|
```
|
|
|
$ chmod +x openfoam-docker
|
|
|
$ ln -sf openfoam-docker openfoam2106-run
|
|
|
$ ln -sf openfoam-docker openfoam2112-run
|
|
|
```
|
|
|
- Verify that the script (or link) can be executed,
|
|
|
and take a look at some of the available options:
|
|
|
```
|
|
|
$ openfoam-docker -help
|
|
|
$ openfoam-docker -help-full
|
|
|
```
|
|
|
|
|
|
- Use the `-dry-run` option if you want to see how the script actually
|
|
|
calls docker, without actually running anything.
|
|
|
```
|
|
|
$ openfoam-docker -dry-run
|
|
|
```
|
|
|
|
|
|
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.
|
|
|
The downloaded openfoam-docker run script is the recommended means to
|
|
|
enter the OpenFOAM image. Assuming that a 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
|
|
|
$ openfoam2112-run
|
|
|
```
|
|
|
|
|
|
This will open an interactive shell with the OpenFOAM environment
|
... | ... | @@ -100,7 +95,11 @@ the default behaviour for the image and run-script. |
|
|
|
|
|
For example,
|
|
|
```
|
|
|
$ openfoam-docker
|
|
|
|
|
|
# With a different OpenFOAM version:
|
|
|
$ openfoam-docker -2012
|
|
|
|
|
|
```
|
|
|
|
|
|
|
... | ... | @@ -108,71 +107,120 @@ $ openfoam-docker -2012 |
|
|
|
|
|
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 this, the standard `--` or `-` separators can be used, but a
|
|
|
single isolated `/` also works and provides a nice visual separation.
|
|
|
For example,
|
|
|
```
|
|
|
$ openfoam-docker -2012 -- blockMesh -help
|
|
|
$ openfoam-docker / blockMesh -help
|
|
|
```
|
|
|
|
|
|
It is also possible to use the run-script to run shell scripts.
|
|
|
For example,
|
|
|
```
|
|
|
$ openfoam-docker -2012 -c './Allrun'
|
|
|
$ openfoam-docker -c './Allrun'
|
|
|
```
|
|
|
|
|
|
Note that the entry point within the image itself also has some option
|
|
|
handling.
|
|
|
For example,
|
|
|
```
|
|
|
$ openfoam-docker -2012 -- -help
|
|
|
$ openfoam-docker / -help
|
|
|
```
|
|
|
|
|
|
|
|
|
## Frequently Asked Questions about Docker
|
|
|
## Installing Docker
|
|
|
|
|
|
- _Is there any performance degradation when running via Docker?_<br/>
|
|
|
- On Linux, the docker should run as quickly natively hosted code.
|
|
|
- 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 (Linux only):
|
|
|
|
|
|
| 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 |
|
|
|
|
|
|
|
|
|
## Frequently Asked Questions
|
|
|
|
|
|
- <em>Is there any performance degradation when running via Docker?</em><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
|
|
|
- <em>Why is slow on ARM-based machines?</em><br/>
|
|
|
Since the standard docker images are AMD64-based, the _AMD64_
|
|
|
emulation layer is cause of the slowdown here. If you just want to
|
|
|
test a few commands this probably will not bother you, but if you want
|
|
|
to use OpenFOAM more extensively you need an ARM64-based image. See
|
|
|
next question.
|
|
|
|
|
|
- <em>Can I rebuild my own image?</em><br/>
|
|
|
This is no problem. All of the files needed are provided on the
|
|
|
[packaging/containers][packaging-containers] repository.<br/>
|
|
|
If you have an ARM-based machine, you should use the openSUSE Leap
|
|
|
components (see the openfoam-run_leap.Dockerfile from the repo).
|
|
|
The standard images are usually AMD64 Ubuntu images and the Ubuntu
|
|
|
OpenFOAM packages for ARM may be outdated or missing. However, the
|
|
|
OpenFOAM ARM packages for openSUSE Leap are fully aligned.
|
|
|
|
|
|
- <em>Can I reuse the docker images?</em><br/>
|
|
|
That is the beauty of containers. Simply start from any given image
|
|
|
(include these OpenFOAM images) and define your own layers.
|
|
|
|
|
|
- <em>How do I check if the OpenFOAM image has been downloaded correctly?</em><br/>
|
|
|
The command
|
|
|
```
|
|
|
$ docker images
|
|
|
```
|
|
|
to show the images available in Docker environment. For example,
|
|
|
shows the local images available. 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
|
|
|
opencfd/openfoam2112-run latest xxxxxxxxxxxx N days ago 640MB
|
|
|
opencfd/openfoam2112-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)
|
|
|
|
|
|
- <em>I prefer to use **podman** instead of **docker**</em><br/>
|
|
|
No worries, like `openfoam-docker -help-full` shows, that option is
|
|
|
also available:
|
|
|
```
|
|
|
$ openfoam-docker -podman
|
|
|
```
|
|
|
How do I check if the OpenFOAM image has been downloaded correctly?_<br/>
|
|
|
|
|
|
- <em>Where are my files?</em><br/>
|
|
|
The user files inside Docker are visible (_ie_, mounted) in your home area
|
|
|
and can be operated on just like any other file.
|
|
|
|
|
|
- <em>Why doesn't `paraFoam` display?</em><br/>
|
|
|
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`.
|
|
|
We previously had a long answer here about X-windows access etc, but
|
|
|
in our experience it is simply not worth running paraview within the
|
|
|
docker image. It is much simpler and has better performance to run
|
|
|
ParaView natively on the host operating systems directly.
|
|
|
Use the built-in OpenFOAM reader and/or OpenFOAM data conversion
|
|
|
tools such as `foamToVTK`.
|
|
|
|
|
|
- <em>How do I run parallel?</em><br/>
|
|
|
Same as any other OpenFOAM installation, _e.g._: `mpirun -np 2 icoFoam -parallel`
|
|
|
Same as any other OpenFOAM installation,
|
|
|
_e.g._: `mpirun -np 2 icoFoam -parallel`
|
|
|
|
|
|
- <em>How do I run parallel on multiple computers?</em><br/>
|
|
|
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](/building)
|
|
|
|
|
|
- <em>How do I compile code?</em><br/>
|
|
|
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!)
|
|
|
There are various docker images available, if you use the `-dev` or
|
|
|
`-default` versions, they contains a full OpenFOAM development
|
|
|
environment so all `wmake`, `wclean` _etc._ commands work (it is
|
|
|
running the actual environment OpenFOAM was compiled in!)
|
|
|
|
|
|
- <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
|
... | ... | @@ -187,3 +235,6 @@ Copyright (C) 2020-2021 OpenCFD Ltd. |
|
|
[packaging-containers]: https://develop.openfoam.com/packaging/containers
|
|
|
[dockerhub-opencfd]: https://hub.docker.com/u/opencfd
|
|
|
[run-script]: https://develop.openfoam.com/packaging/containers/-/raw/main/openfoam-docker
|
|
|
|
|
|
[link paraview]: https://www.paraview.org/download/
|
|
|
[faq paraview]: https://discourse.paraview.org/t/i-want-to-visualize-my-openfoam-simulation-results-with-paraview-but-im-confused-which-version-should-i-use |