Using a Singularity Container on Euler

Introduction

The aim of this page is to provide a simple guide on how to run commands in a pre-existing container on Euler. We provide some basic explanations and reference to relevant documentation for mode details.

Basics - Run a simple command in a container

You can see a container as a separate file system that has no visibility on the file system on the cluster. This definition of a container is very limited, but suitable to our current demonstration. A container has its own operating system, that can be the same or a completely different from Euler's OS. To have a detail on what is going on inside of a container, you can either :

• take a look at the container's build recipe, if it is available to you
• use the apptainer shell command, that should open a shell that will give you access to the container's file system

Running a command within a container is straightforward. Let's say that I have installed python 3.12.5 in a container called python3125.sif in my working directory. Then :

$apptainer exec ./python3125.sif python3 --version
Python 3.12.5

$apptainer exec ./python3125.sif python3 -c "print("Hello world")"
Hello world

Any command run on your laptop or Euler proceeded by apptainer exec <path_to_container> will run inside of the container. For additional detailed examples, see the section "Interacting with a container" on the official apptainer tutorial.

Binds - How to make directories on Euler accessible from the container ?

As mentioned in the previous section, a container is a separate file system that has no visibility on the file system on the cluster, with one exception : the working directory. The directory from which you are accessing the container is also mounted on the container. Here is an example :

nmarounina@eu-login-14:~$ pwd #I am on the cluster
/cluster/home/nmarounina
nmarounina@eu-login-14:~$ ls -l
total 212
[...some files...]
drwxr-s---  8 nmarounina nmarounina-group   4096 Jul 29 17:07 print_versions.sbatch
drwxr-sr-x  4 nmarounina nmarounina-group   4096 Jul 29 14:22 python_scripts_cluster
-rw-r-xr-x  1 nmarounina nmarounina-group 150043 Jul 29 14:18 python_test_ML.py
drwxr-x---  7 nmarounina nmarounina-group   4096 Apr 25 15:28 work_tickets
[... etc ...]
nmarounina@eu-login-14:~$ ls / #This is what we have in the root directory on the cluster
total 32
lrwxrwxrwx   1 root root     7 Jul  1 17:49 bin -> usr/bin
drwxr-xr-x   4 root root   280 Jul 10 11:48 boot
drwxr-xr-x  14 root root   162 Jul 22 06:48 cluster
drwxr-xr-x  20 root root  4360 Aug  2 21:27 dev
drwxr-xr-x 107 root root  8192 Aug 17 06:12 etc
drwxr-xr-x   2 root root     6 Apr 18  2022 home
lrwxrwxrwx   1 root root     7 Jul  1 17:49 lib -> usr/lib
lrwxrwxrwx   1 root root     9 Jul  1 17:49 lib32 -> usr/lib32
lrwxrwxrwx   1 root root     9 Jul  1 17:49 lib64 -> usr/lib64
lrwxrwxrwx   1 root root    10 Jul  1 17:49 libx32 -> usr/libx32
drwxr-xr-x   5 root root    43 Jul 10 11:31 local
drwxr-xr-x   2 root root     6 Jul  1 17:49 media
drwxr-xr-x   2 root root     6 Jul  1 17:49 mnt
drwxr-xr-x   2 root root     0 Aug 20 08:08 nfs
drwxr-xr-x   2 root root     0 Aug 10 21:17 nfs4
drwxr-xr-x   2 root root     6 Jul  1 17:49 opt
dr-xr-xr-x 431 root root     0 Nov  6  2023 proc
drwx------   5 root root   163 Aug  2 14:11 root
drwxr-xr-x  27 root root  1140 Aug 20 09:55 run
lrwxrwxrwx   1 root root     8 Jul  1 17:49 sbin -> usr/sbin
drwxrwxrwt   4 root root    38 Aug 16 10:58 scratch
drwxr-xr-x   2 root root     6 Jul  1 17:49 srv
dr-xr-xr-x  13 root root     0 Nov  6  2023 sys
drwxrwxrwt 354 root root 16384 Aug 20 09:57 tmp
drwxr-xr-x  14 root root   160 Jul  1 17:49 usr
drwxr-xr-x  11 root root   139 Jul  1 17:49 var
nmarounina@eu-login-14:~$
nmarounina@eu-login-14:~$ apptainer shell /cluster/apps/nss/alphafold/alphafold-2.3.2/AlphaFold-2.3.2.sif
Apptainer> ls -l #same as before for the working directory
total 212
[...some files...]
drwxr-s---  8 nmarounina nmarounina-group   4096 Jul 29 17:07 print_versions.sbatch
drwxr-sr-x  4 nmarounina nmarounina-group   4096 Jul 29 14:22 python_scripts_cluster
-rw-r-xr-x  1 nmarounina nmarounina-group 150043 Jul 29 14:18 python_test_ML.py
drwxr-x---  7 nmarounina nmarounina-group   4096 Apr 25 15:28 work_tickets
[... etc ...]
Apptainer> 
Apptainer> ls -l /  #However the content of the root directory is completely different
total 28
-rw-r--r--   1 nmarounina nmarounina-group 16047 Oct 28  2022 NGC-DL-CONTAINER-LICENSE
drwxr-xr-x   3 nmarounina nmarounina-group     0 Apr 11 11:46 app
drwxr-xr-x   2 nmarounina nmarounina-group     0 Oct 19  2022 bin
drwxr-xr-x   2 nmarounina nmarounina-group     0 Apr 24  2018 boot
drwxr-xr-x   3 nmarounina nmarounina-group    60 Aug 20 14:35 cluster
drwxr-xr-x  20 nobody     nogroup           4360 Aug  2 20:51 dev
lrwxrwxrwx   1 nmarounina nmarounina-group    36 Apr 11 12:42 environment -> .singularity.d/env/90-environment.sh
drwxr-xr-x   1 nmarounina nmarounina-group    60 Aug 20 14:35 etc
drwxr-xr-x   2 nmarounina nmarounina-group     0 Apr 24  2018 home
drwxr-xr-x   8 nmarounina nmarounina-group     0 Apr 11 11:38 lib
drwxr-xr-x   2 nmarounina nmarounina-group     0 Oct 19  2022 lib64
drwxr-xr-x   2 nmarounina nmarounina-group     0 Oct 19  2022 media
drwxr-xr-x   2 nmarounina nmarounina-group     0 Oct 19  2022 mnt
drwxr-xr-x   4 nmarounina nmarounina-group     0 Apr 11 11:39 opt
dr-xr-xr-x 502 nobody     nogroup              0 Jul 31 16:17 proc
drwx------   4 nmarounina nmarounina-group     0 Apr 11 11:45 root
drwxr-xr-x   5 nmarounina nmarounina-group     0 Oct 19  2022 run
drwxr-xr-x   2 nmarounina nmarounina-group     0 Oct 19  2022 sbin
lrwxrwxrwx   1 nmarounina nmarounina-group    24 Apr 11 12:42 singularity -> .singularity.d/runscript
drwxr-xr-x   2 nmarounina nmarounina-group     0 Oct 19  2022 srv
dr-xr-xr-x  13 nobody     nogroup              0 Jul 31 16:17 sys
drwxrwxrwt 101 nobody     nogroup           8192 Aug 20 14:35 tmp
drwxr-xr-x  10 nmarounina nmarounina-group     0 Oct 19  2022 usr
drwxr-xr-x  11 nmarounina nmarounina-group     0 Oct 19  2022 var
Apptainer>

The very common working case might be that you are in need to use a dataset that is on the cluster, let's say stored somewhere in your scratch folder, that you wish to process using a program stored in a container. The solution might then be to bind the relevant folder, so it becomes accessible from the container. The general syntax is :

$apptainer exec mycontainer.sif --bind /source/path/on/cluster:/target/path/within/container, /source/path/on/cluster:/target/path/withinin/container <command_to_run>

You can also set up an environment variable that contains all of the binds. The syntax is similar :

$export APPTAINER_BIND="/source/path/on/cluster:/target/path/within/container,  /source/path/on/cluster:/target/path/withinin/container"
$apptainer exec mycontainer.sif <command_to_run>

Detailed documentation on binding the paths is available here.

Additional options

GPUs

If you wish to use GPUs, please include --nv option :

 $apptainer exec --nv mycontainer.sif <mycommand>

MPI

If you wish to use MPI, the approach is described in the main Singularity/Apptainer page on our wiki.

Submit a Singularity/Apptainer job

Here is our dedicated wiki page on this topic.