Skip to content

Containerisation using Apptainer

BEAR Portal Apps

The apptainer command is not available inside several of the BEAR Portal apps, including JupyterLab, RStudio Server and BlueBEAR GUI. This is because these apps already run inside Apptainer containers.

BlueBEAR supports containerisation using Apptainer. Each node has Apptainer installed on its system, which means that the apptainer command is available without needing to first load a module.

Apptainer (previously Singularity1) is used instead of Docker on high performance computing systems due to the administrative privileges that are required to run the latter. However, Apptainer supports Docker images and can pull from Docker Hub. This means that in many cases it can act as a drop-in replacement for users who are already familiar with containerisation using Docker. Please see below for an outline of Apptainer operations.

Pull and Run

Apptainer can download images from any Open Container Initiative (OCI) repository and further information can be found here. For example, to pull an image from Docker Hub:

apptainer pull docker://python
apptainer pull docker://python:3.4.2 # (to pull a specific tag)

The two common methods for using an Apptainer container are exec and shell:

  • exec runs a command inside a container and then exits the container as soon as the command completes.
  • shell launches a container and then attaches to its shell.

/scratch directory size

Apptainer on BlueBEAR uses the /scratch directory for storing images (when they’ve not been explicitly pulled to another directory) and other container runtime data.
The size of /scratch varies between node-types and if container images are large then the volume can run out of space, which can cause errors. Our recommendation, if you encounter such issues, is to force your job to run on an Ice Lake node by including the following line in your SBATCH headers:

#SBATCH --constraint=icelake


apptainer exec python_3.4.2.sif python --version

will spawn a container from the specified image file, execute the command python --version, print the output and then exit the container.

Accessing Your Data

By default, Apptainer on BlueBEAR binds the following directories from the host node into each running container:

  • /rds: enables access to your home directories and project directories
  • /scratch: access to local disk storage (see here for further info)

Building Containers

--fakeroot not required!

If you have previous experience of building Singularity containers please note that it’s no longer necessary to build using --fakeroot as the required privilege escalation is handled automatically.

To build an image from an Apptainer Definition File, please execute the following commands:

apptainer build my_image.sif my_image_definition.def


If your image definition file includes software compilation then you will need to be aware of the node type on which you build the image, else you might have problems running the image.
Further general information on this can be found here: Self Installing Software for BlueBEAR

Interactive Development

To test development of an Apptainer image interactively use the --sandbox facility, which builds the image as a directory that can then be run with the --writable option.

Suggested workflow:

  1. Run: unset APPTAINER_BIND
  2. Create a sandbox directory either…

    1. from a base OS image, e.g. Rocky Linux:

      apptainer build --fix-perms --sandbox "/scratch/${USER}/my-sandbox-dir" docker://rockylinux:8.6


    2. From an Apptainer definition file:

      apptainer build --fix-perms --sandbox "/scratch/${USER}/my-sandbox-dir" ./my-definition-file.def
  3. Run the sandbox as a container in writeable mode with “root” privileges:

    apptainer shell --fakeroot --writable "/scratch/${USER}/my-sandbox-dir"
  4. Perform the necessary package installs and test your image’s functionality iteratively.

  5. Write the required commands back into an Apptainer Definition File.
  6. Exit the sandbox container.
  7. Build the image from the resultant definition file as per the instructions above.

  1. The Apptainer application replaces the previous HPC containerisation solution, Singularity. It is broadly a drop-in replacement and for now the singularity command is still available, although it will actually execute the Apptainer command.
    For further information on the move from Singularity to Apptainer please see this article