From 4604915036073564ba5ba24962331e8481671825 Mon Sep 17 00:00:00 2001
From: Lars Bilke <lars.bilke@ufz.de>
Date: Fri, 10 Jan 2020 21:27:23 +0100
Subject: [PATCH] [web] Updated container usage docs.
Thanks to M. Binder for reporting issues!
---
.../devguide/troubleshooting/cmake.pandoc | 2 +-
.../docs/userguide/basics/container.pandoc | 32 ++++++++++++-------
2 files changed, 21 insertions(+), 13 deletions(-)
diff --git a/web/content/docs/devguide/troubleshooting/cmake.pandoc b/web/content/docs/devguide/troubleshooting/cmake.pandoc
index 7f0a3a61959..b36e1bfe63f 100644
--- a/web/content/docs/devguide/troubleshooting/cmake.pandoc
+++ b/web/content/docs/devguide/troubleshooting/cmake.pandoc
@@ -11,7 +11,7 @@ weight = 1041
## <i class="far fa-exclamation-triangle"></i> General advice
-If something goes wrong when running CMake please try again with an **empty** or newly created build-directory! This is very first thing you should try!
+If something goes wrong when running CMake please try again with an **empty** or newly created build-directory! This is the very first thing you should try!
Please read the CMake output carefully. Often it will tell you what went wrong.
diff --git a/web/content/docs/userguide/basics/container.pandoc b/web/content/docs/userguide/basics/container.pandoc
index 07250bd1e2b..3c908685656 100644
--- a/web/content/docs/userguide/basics/container.pandoc
+++ b/web/content/docs/userguide/basics/container.pandoc
@@ -18,11 +18,11 @@ weight = 10
### Get a container image
-#### Download a release image
+#### Option: Download a release image (preferred)
Simply download an image from the [releases]({{< ref "/releases" >}}) page.
-#### Create custom image with ogs-container-maker
+#### Option: Create custom image with ogs-container-maker
Build images with [ogs-container-maker](https://github.com/ufz/ogs-container-maker) on [Jenkins](https://jenkins.opengeosys.org/job/ufz/job/ogs-container-maker/job/master/build) (login required, ask Lars Bilke for access):
@@ -33,36 +33,44 @@ It will build all combinations of `format`, `openmpi_versions` and `pm`. When th
### Run OGS inside a Container (called from outside)
```bash
-singularity exec ogs-6.2.0-serial.sif ogs some/path/project.prj
+singularity exec --app ogs ogs-6.2.2-serial.sif ogs some/path/project.prj
```
-This starts the container, mounts your home directory inside the container, passes the current working directory and runs the ogs executable (which is in your home directory which is mounted inside the container) with the passed project file. Everything works as expected and is transparent to the user. When ogs finishes the container stops and you returns to the host system.
+This starts the container, mounts your home directory inside the container, passes the current working directory and runs the ogs executable (in your home directory which is mounted inside the container) with the passed project file. Everything works as expected and is transparent to the user. When ogs finishes the container stops and you returns to the host system.
+
+The `--app ogs` selects a pre-defined execution environment in the container (i.e. setting the `PATH` to `/scif/apps/ogs/bin` in which all the executables are located). You could also run without the `--app`-parameter but then you had to specify the full executable path in the container:
+
+```bash
+singularity exec ogs-6.2.2-serial.sif /scif/apps/ogs/bin/ogs ...
+```
+
+Running a benchmark:
```bash
# Create output directories
mkdir -p _out _out_mpi
# Run serial benchmark
-singularity exec ogs-6.2.0-serial.sif ogs -o _out [ogs-sources]/Tests/Data/Mechanics/Linear/disc_with_hole.prj
+singularity exec --app ogs ogs-6.2.2-serial.sif ogs -o _out [ogs-sources]/Tests/Data/Mechanics/Linear/disc_with_hole.prj
# Run serial benchmark with output validation (via vtkdiff)
-singularity exec ogs-6.2.0-serial.sif ogs -o _out -r [ogs-sources]/Tests/Data/Mechanics/Linear [ogs-sources]/Tests/Data/Mechanics/Linear/disc_with_hole.prj
+singularity exec --app ogs ogs-6.2.2-serial.sif ogs -o _out -r [ogs-sources]/Tests/Data/Mechanics/Linear [ogs-sources]/Tests/Data/Mechanics/Linear/disc_with_hole.prj
# Run parallel benchmark with MPI
-mpirun -np 4 singularity exec ogs-6.2.0-openmpi-2.1.2.sif ogs -o _out_mpi [ogs-sources]/Tests/Data/Mechanics/Linear/disc_with_hole.prj
+mpirun -np 4 singularity exec --app ogs ogs-6.2.2-openmpi-2.1.2.sif ogs -o _out_mpi [ogs-sources]/Tests/Data/Mechanics/Linear/disc_with_hole.prj
```
-You can run other contained executables, e.g. `vtkdiff`:
+You can run other contained executables as well, e.g. `vtkdiff`:
```bash
-singularity exec ogs-6.2.0-serial.sif vtkdiff --help
+singularity exec --app ogs ogs-6.2.2-serial.sif vtkdiff --help
```
You can interactively explore the container with `singularity shell` (you can see that you are **in** the container because of the `Singularity [container image file]:...>` prefix of the shell):
```bash
# Shell into container
-singularity shell ogs-6.2.0-serial.sif
+singularity shell ogs-6.2.2-serial.sif
# List files in the container
-Singularity ogs-6.2.0-serial.sif:...> ls /usr/local/ogs/bin
+Singularity ogs-6.2.2-serial.sif:...> ls /scif/apps/ogs/bin
... ogs tetgen vtkdiff
# Exit the container and get back to your hosts shell
-Singularity ogs-6.2.0-serial.sif:...> exit
+Singularity ogs-6.2.2-serial.sif:...> exit
```
--
GitLab