Introduction to Apptainer/Singularity: Setup

In this document we use the names Apptainer and Singularity interchangeably. See the Introduction for more details about existing Apptainer and Singularity versions and the differences between them.

Option 1: Use pre-installed apptainer on a cluster

Apptainer/Singularity has become popular and usually it is available in the institutional computing resources. Check if apptainer or singularity are available with

apptainer --version
singularity --version

If installed, you will see apptainer version ... or singularity version ..., depending on the flavor installed. Apptainer is preferable but either one is OK, so if apptainer is there, no need to check for singularity (which most likely will be a link to apptainer). This tutorial requires at least Apptainer 1.0.x or Singularity 3.5.x. Previous versions may not have all the required features. If none is in your $PATH or if the available version is too old, you may still be able to use an updated apptainer via CVMFS: check if you have user namespaces enabled and CVMFS to run singularity that way:

[[ $(cat /proc/sys/user/max_user_namespaces) -gt 0 ]] && ls /cvmfs/oasis.opensciencegrid.org/mis/ &>/dev/null && { export PATH=/cvmfs/oasis.opensciencegrid.org/mis/apptainer/bin/:"$PATH"; echo "Success: Added to PATH"; singularity --version; } || echo "Failure: Unable to run Apptainer/Singularity via CVMFS"

If this works, it will be added to your path and you will see your apptainer/singularity version.

If your local computing system does not have Apptainer/Singularity installed, you may request it to your system administrator as suggested here.

Option 2: Install Apptainer/Singularity

You will need a Linux system to run Apptainer/Singularity natively. If you have Linux, go to the Linux install instructions below.

On Windows you can use WSL (Windows Subsystem for Linux). You can run a Linux system on your Windows computer. We recommend AlmaLinux9. Then follow the Linux instructions to install Apptainer as root.

On MacOS you need as well a Linux VM to be able to use Apptainer. There are different solution, here we describe how to use Lima.

Install on a Mac

To avoid architecture problems we recommend to use a x86_64 VM also on ARM Macs. It will be less performant but you’ll avoid architecture errors when images are available only for x86_64. To do so you can use QEMU and Lima via Homebrew.

1. Install QEMU and Lima via Homebrew:

    # Install Homebrew if you don't have it already
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    # Install QEMU and Lima
    brew install qemu lima
   

2. Prepare a x86_64 VM. Here I’m using a Ubuntu image: ```bash # Prepare the VM configuration file cat > ubuntu-x86_64.yaml « EOF arch: “x86_64” images:
   • location: “https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img” arch: “x86_64”
   • location: “https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-arm64.img” arch: “aarch64” # Disable mounts and containerd, otherwise booting up may time out if the host is slow mounts: [] containerd: system: false user: false EOF # Create and start the VM limactl start ubuntu-x86_64.yaml –name=ubuntu limactl shell ubuntu ```
3. In the VM install and use apptainer:

    sudo add-apt-repository -y ppa:apptainer/ppa
    sudo apt install -y apptainer
    # Check your Apptainer version
    apptainer --version
    # You can exit the VM with Ctrl+D (exit)
   

   Now you’re ready to use Apptainer on your Mac. To use Apptainer (and all commands in this tutorial) you have to first enter your VM with limactl shell ubuntu and when you are done you can go back to the Mac shell using exit (Ctrl+d). If you reboot your Mac you may have to restart the VM with limactl start ubuntu. For more commands to control and configure the Lima VM you can check Lima’s documentation.

On Linux, If you have root access

It is easiest to install if you have root access.

On Linux, If not

If the above is not possible and you cannot use the CVMFS distribution you have still an option if user namespace is enabled on your system:

1. Check if user namespaces are enabled:

    # on Debian/Ubuntu
    grep -q 'kernel.unprivileged_userns_clone=1' /etc/sysctl.d/90-unprivileged_userns.conf && \
        echo "User namespaces enabled, continue the Apptainer installation" || \
        echo "User namespaces NOT enabled, your use of Apptainer will be very limited"
    # on RHEL/CentOS cat /proc/sys/user/max_user_namespaces` is bigger than 0
    [[ $(cat /proc/sys/user/max_user_namespaces) -gt 0 ]] && \
        echo "User namespaces enabled, continue the Apptainer installation" || \
        echo "User namespaces NOT enabled, your use of Apptainer will be very limited"
   

   See these full instructions for more about checking for and enabling user namespaces.

2. If enabled, install unprivileged Apptainer with one of these three methods (in order of preference):
   1. Chose your INSTALL_DIR and install there the relocatable Apptainer (recommended). Run:

       curl -s https://raw.githubusercontent.com/apptainer/apptainer/main/tools/install-unprivileged.sh | \
           bash -s - INSTALL_DIR
      

   2. Alternatively install from source without root privileges.
   3. Or use cvmfsexec to get CVMFS. This is a bit more complex, you can follow the instrictions summarized also in this paper.

If user namespaces are not enabled, apptainers/singularity is not installed, and you have no root access to the host, then your use of apptainer/singularity will be very limited even if you install it with one of the three methods above. You need to request to your system administrator to either install Apptainer/Singularity or to enable user namespaces.