====== Container Technology ======

Building more complex processing and analysis pipelines within a container can offer several advantages:

   * The container fully encapsulates the job and all software dependencies
   * Software dependencies do not need to be installed on the HPC facility
   * Your workflow can easily be replicated or moved between other systems
   * You can run //pre-built// job containers which application developers publish
   * You can build //your own// containers to move between systems, or share with your group

The **Comet** HPC facility supports the following container tools:

   * [[#docker|Docker]]
   * [[#apptainer|Apptainer]]
   * [[#apptainer|Singularity]] - Now //deprecated// and replaced by [[#apptainer|Apptainer]]
   * [[#podman|Podman]] - RedHat Linux specific container toolset, largely compatible with Docker

<WRAP todo round>
**This section is incomplete**

This documentation section on //Container Technology// is still being written and will not be complete until the **Comet** HPC facility is fully commissioned.
</WRAP>
===== Docker =====

----
===== Apptainer =====

If you have used Singularity previously, then Apptainer is a 100%, like-for-like replacement.

   * [[https://apptainer.org/docs/user/main/quick_start.html|Apptainer quick start guide]]
   * [[https://apptainer.org/docs/user/main/build_a_container.html|Building containers]]
   * [[https://github.com/apptainer/apptainer|Apptainer Github repository & issues]]

=== Download and run a pre-built container ===

Following the Apptainer [[https://apptainer.org/docs/user/main/quick_start.html|Quick Start]] guide, we can test everything is working by using the **lolcow** container image - this is a tiny Linux container that contains the ''cowsay'' tool, simply printing a string of text to the screen from an ASCII-art cow.

Load the Apptainer module:

<code lang=bash>
$ module load apptainer
$ apptainer version
1.4.1
$
</code>

Download an existing (Docker) container image from the Github container registry, and convert to Apptainer/Singularity ''.sif'' format:

<code lang=bash>
$ module load apptainer
$ apptainer pull docker://ghcr.io/apptainer/lolcow
INFO:    Converting OCI blobs to SIF format
INFO:    Starting build...
INFO:    Fetching OCI image...
45.8MiB / 45.8MiB [============================================================] 100 % 20.3 MiB/s 0s
27.2MiB / 27.2MiB [============================================================] 100 % 20.3 MiB/s 0s
INFO:    Extracting OCI image...
INFO:    Inserting Apptainer configuration...
INFO:    Creating SIF file...
INFO:    To see mksquashfs output with progress bar enable verbose logging
$
</code>

Run an Apptainer (or Singularity) container image:

<code lang=bash>
$ apptainer exec lolcow_latest.sif cowsay "HPC is cool!"
 ______________
< HPC is cool! >
 --------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||
$
</code>

=== Build a new container ===

TBD

=== Run Apptainer container under Slurm ===

Running the container image pulled down previously, we can easily run the same commands under Slurm on a compute node:

<code lang=bash title=cowsay.sh>
#!/bin/bash

#SBATCH --partition=default_free
#SBATCH -c 1
#SBATCH -t 00:05:00

module load apptainer

###########################################
echo "Starting Apptainer image on $HOSTNAME..."
apptainer exec lolcow_latest.sif cowsay "Help, I'm trapped in a container running under Slurm on $HOSTNAME!"
echo "Job completed!"
###########################################
</code>

Submit as:

<code lang=bash>
$ sbatch cowsay.sh
Submitted batch job 1022834
$
</code>

Check the output:

<code lang=bash>
$ cat slurm-1022834.out
Starting Apptainer image on compute030...
/ Help, I'm trapped in a container     \
\ running under Slurm on compute30!    /
 --------------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||
Job completed!
$
</code>

==== Errors Building Apptainer Containers ====

Apptainer normally assumes the user is a member of ''sudoers'' to create images, but has a workaround called //user namespaces// to allow unprivileged users to create images without needing elevated permissions.

//User namespaces// is enabled on the login nodes of Comet and therefore creating almost any type of container should work correctly.

One limitation to this is that //user namespaces// only work fully on **local** filesystems - if you try to **build** a container on ''$HOME'' or ''/nobackup'' you may find that you get odd permission errors during the container installation process (references to "unable to change group" or "cannot install setuid binary" or similar).

Ensure that if building a container from a definition file which include post-install commands (e.g. ''apt'', ''yum'' or similar) that you set the following environment variable prior to running the build:

<code lang=bash>
export APPTAINER_TMPDIR=/tmp/
</code>

To be clear: __running__ an existing container from ''$HOME'' or ''/nobackup'' is __fully supported__; only the initial build process needs to be performed in ''/tmp'', via the **APPTAINER_TMPDIR** variable, above.

Please __build__ your containers on the login nodes - it is __not__ supported on compute nodes.

----

===== Singularity =====

Singularity is now deprecated and the community have largely moved to Apptainer instead. Apptainer is a like-for-like, drop-in replacement for Singularity; if you have previously used Singularity, then you can start using Apptainer by simply changing any call to ''singularity'' to ''apptainer'' instead.

Historically we //did// have Singularity on our previous **Rocket** HPC facility, but it was not advertised and was very much a "use at your own risk" capability.
===== Podman =====



----

[[advanced:index|Back to Advanced Topics]]