Use Singularity on IU's research supercomputers

• Overview
• Singularity at IU
• Singularity commands
• Use Singularity with Docker containers
• Bind mount Slate, Slate-Project, and Slate-Scratch directories
• Useful options
• Get help

---

Overview

Singularity is a container solution that promotes reproducible science by giving researchers the ability to run their scientific applications and workflows in a variety of different Linux-based operating system (OS) environments.

A Singularity container is an encapsulation of an application and its dependencies (the libraries, packages, and data files it needs for execution), which is saved as a single, distributable image file. The image file can be copied, shared, and launched without modification in most Linux-based OS environments (as long as the destination host has Singularity installed). When the image launches, the container daemon executes on the host, virtualizes the contained application's OS environment, and then runs the application inside the virtualized environment, allowing you (as a non-root user on a shared HPC resource), to run your application even when it cannot be natively installed or supported on the host due to OS and/or library incompatibilities or conflicts.

Because the Singularity container runs on the host's kernel, it's able to leverage the host's physical hardware (for example, GPUs and accelerators), interconnects, and file systems, giving the contained application the same performance characteristics as native applications. Singularity also natively supports HPC resource managers and job schedulers, and features built-in Open MPI support.

Although some aspects of container execution require escalated privileges, all escalated privileges are dropped once the container environment is instantiated. Singularity also prevents user context escalation within the container. Although root privileges are not needed to run them, Singularity images can be built, configured, and/or modified only on hosts for which the user has root privileges.

Singularity was developed under the leadership of Gregory Kurtzer, Linux Cluster Technical Architect for the Berkeley Research Computing High Performance Computing service. For more, see the Singularity website.

Singularity at IU

Singularity is available on the IU research supercomputers. To get starting using Singularity, add it to your user environment with the following command:

module load singularity

Although Singularity containers will run on the IU research supercomputers, you first should contact the UITS Research Applications and Deep Learning team to check whether they can install your application natively.

If you have a Singularity container image that you want to use (after ruling out native installation), contact the UITS Research Applications and Deep Learning team for help migrating it to your space on an IU research system. Most likely, you will need to modify your image to add appropriate mount points; you can modify a Singularity container only on systems for which you have root privileges (not on IU's research systems).

Singularity commands

Singularity uses a primary command wrapper called singularity, several sub-commands, and global and command-level options. To see a list of Singularity sub-commands and options, on the command line, enter singularity (without any options).

The general syntax for the singularity command wrapper is:

singularity [global options] <sub-command> [sub-command options] <container_path>

Following are some sample Singularity commands (replace /N/slate/username/my_image.img with the path to your Singularity container):

• To spawn a shell within your container, on the command line, enter:

  singularity shell /N/slate/username/my_image.img

  To see options available for the shell sub-command, on the command line, enter singularity shell -h. For more, see singularity shell in the Singularity User Guide.

• To execute a program inside your Singularity container (for example, /path/inside/container/go_fish), on the command line, enter:

  singularity exec /N/slate/username/my_image.img /path/inside/container/go_fish

  To see options available for the exec sub-command, on the command line, enter singularity exec -h. For more, see singularity exec in the Singularity User Guide.

As mentioned previously, you can modify Singularity containers only on systems for which you have root privileges (not on the IU research supercomputers). Furthermore, by default, all Singularity containers are read-only. To make your container's file system accessible in writable mode, add the -w option to your Singularity sub-commands. For example, to spawn a writable shell in your container (for example, my_image.img, on the command line (of the system on which you are root), enter:

singularity shell -w my_image.img

Use Singularity with Docker containers

You can use Singularity's pull sub-command to import a container image directly from Docker Hub without having root or superuser privileges (or Docker) on your host system. For example, to use Singularity to import the image of the latest long-term support (LTS) version of Ubuntu into the present working directory on your host system, use the following command:

singularity pull docker://ubuntu:latest

Alternatively, you can use Singularity's shell sub-command to spawn an interactive shell within a Docker container "on the fly". In the following example, user bkyloren on Carbonate shells into the latest LTS Ubuntu image available on Docker Hub:

[bkyloren@h1 ~]$ singularity shell docker://ubuntu:latest
Docker image path: index.docker.io/library/ubuntu:latest
Cache folder set to /gpfs/home/b/k/bkyloren/Carbonate/.singularity/docker
[5/5] |===================================| 100.0%
Creating container runtime...
WARNING: Could not create bind point file
in container /etc/localtime: No such file or directory
Singularity: Invoking an interactive shell within container...

Singularity ubuntu:latest:~>

For more about using Singularity to work with Docker images, see Singularity and Docker and singularity pull in the Singularity User Guide.

Bind mount Slate, Slate-Project, Slate-Scratch directories

To make directories on Slate, Slate-Project, and Slate-Scratch accessible from within your Singularity container, you must manually bind mount them by adding the -B (--bind) option to your shell or exec command. The -B option lets you specify the source and destination bind paths outside and inside the container, respectively. If you do not specify the destination path, the mount point inside the container is set automatically to equal the source path. To bind mount multiple directories in a single command, you can specify the -B option multiple times, or use a comma-delimited string of bind path specifications.

For example:

• To make your space on Slate available within your container, start the container with the following command (replace username with your IU username and my_container.sif with the path to your container):

  singularity shell -B /N/slate/username my_container.sif
  

  The above command binds Slate directory /N/slate/username to a mount point of the same name (/N/slate/username) inside the container.

• To make your Slate-Scratch directory available within your container from a mount point named, for example, /mnt, start the container with the following command (/mnt does not have to already exist in the container; replace username with your IU username and my_container.sif with the path to your container):

  singularity shell -B /N/scratch/username:/mnt my_container.sif
  

  The above command binds Slate directory /N/slate/username to the /mnt mount point inside the container (/mnt does not have to already exist in the container).

• To bind mount your Slate, Slate-Project, and spaces, start the container with the following command replace username with your IU username, projectname with your Slate-Project project name, and my_container.sif with the path to your container):

  singularity shell -B /N/slate/username,/N/project/projectname,/N/scratch/username my_container.sif

  The above command binds Slate directory /N/slate/username, Slate-Project directory /N/project/projectname, and Slate-Scratch directory /N/scratch/username to mount points of the same name inside the container.

Useful options

Following are some Singularity options you may find useful:

Get help

If you have questions or need help using Singularity on an IU research supercomputer, contact the UITS Research Applications and Deep Learning team.