Document the usage of the project's autogenerated docker image

README.md

@@ -149,6 +149,71 @@ cmake -DGEOMODELATLAS_BUILD_ALL=1 -DCMAKE_INSTALL_PREFIX=../install ../GeoModelA
 
 In the example above, `make install` will install everything in the folder `../install`, with the path relative to the `build` folder.
 
+## Docker image
+
+As an alternative to locally installing and / or building `GeoModel` and `GeoModelATLAS`, there is also a `[docker](https://www.docker.com/)` image available for this project.
+It includes all the required dependencies and delivers an 'out of the box' experience. 
+
+The available images are listed in the project's [container registry](https://gitlab.cern.ch/atlas/geomodelatlas/GeoModelATLAS/container_registry). 
+
+### Getting set 
+To be able to run a container based on this image: 
+
+* Install [docker](https://www.docker.com/) on your system in case it is not yet available. You might also be able to use the `singularity` installation supplied via `cvmfs`, but this has not yet been tested. 
+* If you haven't done so in the past, you will need to log in to the CERN gitlab registry once: 
+```
+docker login gitlab-registry.cern.ch
+```
+* Then, you can pull the `geomodelatlas` image: 
+```
+docker pull gitlab-registry.cern.ch/atlas/geomodelatlas/geomodelatlas:master
+``` 
+This will make a local image available on your computer that you can use to launch containers. 
+To list the available images, you can use `docker images`. 
+
+### Running a container 
+* You can now start up a container using a single command. Please see the [reference](https://docs.docker.com/engine/reference/run/) for the `docker run` command for a detailed documentation of the available options. 
+
+We will want to start an interactive shell, make parts of our file system available (to be able to work with our local geometry files), and ensure that X-forwarding is possible so that we can display graphical applications. 
+
+The details of the prompt will change slightly depending on your OS and preferences, the general format is: 
+```
+docker run -w ${PWD} -v ${PWD}:${PWD} -e DISPLAY=$DISPLAY -it gitlab-registry.cern.ch/atlas/geomodelatlas/geomodelatlas:master
+```
+
+The `-v` option allows you to make file system paths available within the container. The syntax is `-v <local path>:<path to make it available on>`. 
+
+In my example above, I assume I am in the working directory within which all my sources / geometry files are located. 
+
+With `-e`, you can specify environment variables. The `DISPLAY` variable is definitely needed. 
+
+For users of the [GeoModelXML plugin](https://gitlab.cern.ch/atlas/geomodelatlas/GeoModelATLAS/-/tree/master/GeoModelXML), it can be useful to also set `-e LANG=en_US.UTF-8`.
+
+#### Note for MacOS:
+
+On MacOS, you need to have `XQuartz` installed (also in case you compile from source) and in the `XQuartz` security settings, you need to allow network client connections. You need to specify the `DISPLAY` variable when running docker and note that you need to pass the docker image ID (you find it by `docker images`):
+```
+xhost + "$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}')"
+docker run -e DISPLAY="$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}')":0  -w ${PWD} -v ${PWD}:${PWD} -it <image ID> 
+```
+
+#### Note for Windows 10 with Windows Subsystem for Linux (WSL):
+
+In case you are using Windows 10 with the Windows Subsystem for Linux (WSL), you might be interested in this Twiki in general: https://twiki.cern.ch/twiki/bin/view/Sandbox/RunningATLASOnWSL2
+You'll need to install an X server (for example, [VcXsrv](https://sourceforge.net/projects/vcxsrv/)), as Windows doesn't ship with one. 
+In addition, you will need to add exceptions to your windows firewall to allow connections to your X-server program. 
+When running docker, you then have to set the `DISPLAY` variable via
+```
+docker run -e DISPLAY="$(grep nameserver /etc/resolv.conf  | awk '{print $2}'):0.0" -w ${PWD} -v ${PWD}:${PWD} -it gitlab-registry.cern.ch/atlas/geomodelatlas/geomodelatlas:master
+```
+
+### Where to find the libraries within the container? 
+If you have the container running and need to find libraries (for example the GMX plugin), you can find them under `/usr/local/lib`.
+
+For example, to run `gmex` with the `GeoModelXML` plugin, you could call 
+```
+GMX_FILES=<path_to_my_gmx_file> gmex /usr/local/lib/libGMXPlugin.so
+```
 
 ## LICENSE