Singularity

Singularity is a container platform, perhaps the most well-supported Docker alternative. It allows you to run containers that package up pieces of software in a way that is portable and reproducible. You can build a container using Singularity on your laptop, self-managed desktop or a virtual machine and then run it on a DICE desktop or server or even move it to the cloud or a HPC cluster.

Note that on DICE we now provide the Open-Source Apptainer system which is fully compatible with Singularity. Apptainer is currently available on all Ubuntu Compute and Teaching Cluster nodes (landonia nodes).

Full documentation can be found here: Apptainer user's guide

Using Apptainer on DICE

Apptainer is only available on DICE Ubuntu.

Check that it is installed by simply running this command in a terminal window:

apptainer --version

If this returns command not found please raise a ticket requesting for its installation on your DICE machine.

The most common usage of Apptainer is to download pre-built images from an external resource like the Container Library or Docker Hub.

Singularity was configured to use Sylabs servers for libraries by default. You will now need to specify your own (see the docs for more details), like this:

apptainer remote add --no-login SylabsCloud cloud.sycloud.io
apptainer remote use SylabsCloud

You can use search command to locate groups, collections, and containers of interest on the Container Library.

This will output an extensive list of all containers on the Container Library built around tensorflow.

apptainer search tensorflow

You can use the pull command to download pre-built images.

apptainer pull library://lolcow

for Container Library images or

apptainer pull docker://sylabsio/lolcow

for Docker Hub images

Apptainer and AFS

When pulling images from Container Library a single image file (.sif) is downloaded. When pulling images from Docker Hub the image will be built on the fly. For this reason Apptainer uses temporary and cache folders. As the default location for these folders is inside your home folder (~/.apptainerAPPTAINER_TMPDIR and APPTAINER_CACHEDIR. Please consider adding these to your .brc or .bashrc file. The below is just an example:

export APPTAINER_TMPDIR=/disk/scratch/$USER/singularity/temp
export APPTAINER_CACHEDIR=/disk/scratch/$USER/singularity/cache

You may need to create those directories, like this:

mkdir -p /disk/scratch/$USER/singularity/temp /disk/scratch/$USER/singularity/cache

Interacting with images

The shell command allows you to spawn a new shell within your container and interact with it as though it were a small virtual machine.

apptainer pull library://lolcow
apptainer shell lolcow_latest.sif 
Singularity>

The change in prompt (to Singularity) indicates that you have entered the container. Once inside the container, you are the same user as you are on the DICE machine. You can leave the container by entering exit or using the standard ctrl-d key combination.

The exec command allows you to execute a custom command within a container by specifying the image file. For instance, to execute the cowsay program within the lolcow_latest.sif container:

apptainer exec lolcow_latest.sif cowsay moo
 _____
< moo >
 -----
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Singularity containers contain runscripts. These are user defined scripts that define the actions a container should perform when someone runs it. The runscript can be triggered with the run command, or simply by calling the container as though it were an executable. Both commands below will give the same result.

apptainer run lolcow_latest.sif

or

./lolcow_latest.sif

Working with files

By default Apptainer bind mounts your home folder, /tmp and current working directory into the container at runtime. You can specify additional directories to bind mount into your container with the --bind option. e.g:

apptainer shell lolcow_latest.sif 
Singularity> ls /disk/scratch
ls: cannot access '/disk/scratch': No such file or directory
Singularity> exit
apptainer shell --bind /disk/scratch lolcow_latest.sif 
Singularity> ls /disk/scratch/
lost+found  miniconda3

Working with GPUs

Apptainer does not bind GPU(s) to containers by default. Please use --nv parameter to do so.

apptainer shell --nv lolcow_latest.sif 
Singularity> nvidia-smi
Thu Jun 30 13:39:59 2022       
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 470.129.06   Driver Version: 470.129.06   CUDA Version: 11.4     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |

                                      (...)
|  No running processes found                                                 |
+-----------------------------------------------------------------------------+

Build images from scratch

To build containers requires a machine you have root privileges for. As this is not the scope of this quick start guide please refer to Apptainer user's guide.

For any issues or further help please use the computing support form.