Added 'Run a container example' to open-ondemand/apps/job-composer.md (#282)

Added 'Run a container example' to open-ondemand/apps/job-composer.md

Author: mikej888

docs/safe-haven-services/open-ondemand/apps/job-composer.md

@@ -207,3 +207,177 @@ If you selected a back-end where your home directory is not common to both the O
     ```
     Hello World to someuser from some-vm.nsh.loc
     ```
+
+---
+
+## Run a container example
+
+This example demonstrates how to create and submit a Slurm job that runs a bash script that runs the 'hello TRE' container which is used within the [Getting started](../getting-started.md) and the [Run Batch Container](./batch-container-app.md) app. The container is run using the TRE Container Execution Tools' commands `ces-pull`, to pull the container, and `ces-run` to run the container.
+
+Create a job to run the container using Podman:
+
+1. Select **New Job** menu, **From Template** option.
+1. Enter Job Name: Run Container
+1. Select a Cluster, back-end.
+1. Click **Create New Job**.
+1. Under 'main_job.sh', click **Open Editor**.
+1. A new browser tab will appear with an editor.
+1. Update the script as follows:
+
+    ```bash
+    #!/bin/bash
+    #SBATCH --job-name=hello-tre
+    #SBATCH --output=output.txt
+    #SBATCH --ntasks=1
+    #SBATCH --time=10:00
+    #SBATCH --mem-per-cpu=100
+
+    CR_URL=git.ecdf.ed.ac.uk/tre-container-execution-service/containers/epcc-ces-hello-tre:1.1
+    CR_USER=anonymous
+    CR_TOKEN=...see below...
+    ces-pull podman $CR_USER $CR_TOKEN $CR_URL
+
+    export CES_SCRATCH=$HOME/scratch/hello-tre
+    export CES_SAFE_OUTPUTS=$HOME/safe_outputs/hello-tre
+    mkdir -p $CES_SCRATCH
+    mkdir -p $CES_SAFE_OUTPUTS
+
+    cat << EOF > env_file.txt
+    HELLO_TRE=Greetings
+    EOF
+
+    cat << EOF > arg_file.txt
+    -d 10
+    -n $USER
+    EOF
+
+    ces-run podman -n hello-tre --env-file env_file.txt --arg-file arg_file.txt $CR_URL
+    ```
+
+    * For `CR_TOKEN`, copy in the 'hello TRE' container's 'Container registry access token' from the [Run Batch Container](./batch-container-app.md) app's form.
+    * By default, `ces-run` creates directories with random names - `scratch-NNNN` and `outputs-NNNN` - and mounts these into a container at `/scratch` and `/safe_outputs`. However, `ces-run` supports `CES_SCRATCH` and `CES_SAFE_OUTPUTS` environment variables, which allow for existing directories to be used. In the script above, we create subdirectories of `$HOME` and define `CES_SCRATCH` and `CES_SAFE_OUTPUTS` to tell `ces-run` to mount these directories.
+    * The script creates a file, `env_file.txt`, with an environment variable to be passed to the 'hello TRE' container. The container uses the environment variable `HELLO_TRE` to customise the greeting it prints.
+    * The script also creates a file, `arg_file.txt`, with container-specific arguments to be passed directly to the container when it is run. The 'hello TRE' container will pause for `-d` seconds, then issue a greeting to the name cited in `-n` (here, the current user).
+
+1. Click **Save**.
+
+Submit job:
+
+1. Switch to the Job Composer browser tab.
+1. Click **Submit job** (green play icon).
+
+    ![Submit Job button, a green play icon](../../../images/open-ondemand/job-composer-play-button.png){: class="border-img center"} ***Submit Job** button*
+
+1. The job 'Status' should go from 'Queued' to 'Completed'.
+
+If you selected a back-end where your home directory is common to both the Open OnDemand VM and the back-end, then:
+
+1. Click `output.txt` under **Folder Contents**.
+1. A new browser tab will appear with the contents of the file:
+
+    ```text
+    ...
+    Hello TRE!
+    ...
+    Greetings USER!
+
+    Sleeping for 10 seconds...
+    1
+    2
+    3
+    4
+    5
+    6
+    7
+    8
+    9
+    10
+    ...and awake!
+
+    For more container examples and ideas, visit:
+      https://github.com/EPCCed/tre-container-samples
+    Goodbye USER!
+    ```
+
+1. Close the tab.
+
+If you selected a back-end where your home directory is not common to both the Open OnDemand VM and the back-end, then:
+
+1. Click **Open Terminal** to log into the back-end on which the job was run. Once logged in, your current directory will be changed to match the job context directory.
+1. View the job context directory's contents:
+
+    ```bash
+    ls -1
+    ```
+
+    ```text
+    arg_file.txt
+    env_file.txt
+    main_job.sh
+    output.txt
+    ```
+
+1. View `output.txt`:
+
+    ```bash
+    cat output.txt
+    ```
+
+    ```text
+    ...
+    Hello TRE!
+    ...
+    Greetings USER!
+
+    Sleeping for 10 seconds...
+    1
+    2
+    3
+    4
+    5
+    6
+    7
+    8
+    9
+    10
+    ...and awake!
+
+    For more container examples and ideas, visit:
+      https://github.com/EPCCed/tre-container-samples
+    Goodbye USER!
+    ```
+
+Create a new job from the current job to run the container using Apptainer:
+
+1. Switch to the Job Composer browser tab.
+1. Select **New Job** menu, **From Selected Job** option.
+1. Under 'main_job.sh', click **Open Editor**.
+1. Replace use of `podman` with `apptainer` as follows:
+
+    1. Replace the `ces-pull podman` line with:
+
+        ```bash
+        cd $HOME
+        ces-pull apptainer $CR_USER $CR_TOKEN $CR_URL
+        SIF_FILE=$HOME/epcc-ces-hello-tre:1.1.sif
+        cd $SLURM_SUBMIT_DIR
+        ```
+
+        * `ces-pull apptainer` creates a SIF file in the current directory whose name is derived from the last part of the container URL. We change into `$HOME` so that the SIF file is created in `$HOME` before moving back to the directory with the job files, `$SLURM_SUBMIT_DIR`. This means we'll only ever have one copy of this SIF file in our `$HOME` directory, rather than one copy for each run of the job, which would quickly consume space!
+
+    1. Replace the `ces-run podman` line with:
+
+        ```bash
+        ces-run apptainer -n hello-tre --env-file env_file.txt --arg-file arg_file.txt $SIF_FILE
+        ```
+
+Submit job:
+
+1. Switch to the Job Composer browser tab.
+1. Click **Submit job** (green play icon).
+
+    ![Submit Job button, a green play icon](../../../images/open-ondemand/job-composer-play-button.png){: class="border-img center"} ***Submit Job** button*
+
+1. The job 'Status' should go from 'Queued' to 'Completed'.
+
+View `output.txt` as described previously.