Skip to content

Singularity (containers)

A Docker-compatible container platform for HPC

Homepage Version(s): 3.8.1

Software containerization is a popular solution for environment-level reproducibility. Singularity is a software containerization solution for HPC and cluster systems such as the FSU HPC. It is compatible with Docker and is capable of automatically converting Docker containers to Singularity containers

Note

Singluarity was recently rebranded as Apptainer, but we have not upgraded yet. When we do, we will update this page to reflect the latest command names and branding.

Basic Usage#

The singularity command is available by default when you log in to the HPC cluster.

1
2
[USERNAME@h22-login-24 ~]$ singluarity --version
singularity version 3.8.1-2.el83

The run command syntax is as follows:

1
$ singularity [OPTIONS] run CONTAINERNAME

Full Singularity documentation and examples use are available at the official Singularity User Guide.

A note about Docker#

Docker is NOT available on the HPC. We require all users needing to use Docker containers convert them to Singularity containers. See below for instructions on how to convert/import Docker containers to Singularity.

Running Docker containers in Singularity#

Note

This is a summary of the documentation found at the official documentation site.

To run a Docker container in Singularity on the HPC, execute the command, singlarity run docker://[REPO]/[IMAGE:TAGS]. For example, to run the lolcow image provided by Syslabs:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
$ singularity run docker://syslabsio/lolcow:latest
INFO:    Converting OCI blobs to SIF format
INFO:    Starting build...
Getting image source signatures
Copying blob 16ec32c2132b done  
Copying blob 5ca731fc36c2 done  
Copying config fd0daa4d89 done  
Writing manifest to image destination
Storing signatures
2023/05/23 13:10:02  info unpack layer: sha256:16ec32c2132b43494832a05f2b02f7a822479f8250c173d0ab27b3de78b2f058
2023/05/23 13:10:03  info unpack layer: sha256:5ca731fc36c28789c5ddc3216563e8bfca2ab3ea10347e07554ebba1c953242e
INFO:    Creating SIF file...
 ______________________________
< Tue May 23 13:10:09 EDT 2023 >
 ------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

The first time you run this command, it will automatically download the Docker image and convert it into a .sif image file. The .sif file will be stored in your home directory in a hidden folder: ~/.singularity.

Subsequent runs will use the cached image file, unless you specify otherwise:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
$ singularity run docker://sylabsio/lolcow
INFO:    Using cached SIF image
 ______________________________
< Tue May 23 13:18:59 EDT 2023 >
 ------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

To "bust" the cache, and pull the original image, add the --disable-cache option:

1
$singularity run --disable-cache docker://sylabsio/lolcow

Specifying a custom cache directory#

By default, Singularity creates a hidden directory in your home directory for building/converting workflows:

1
2
$ ls ~/.singularity
cache  docker  metadata  sypgp

Singularity typically cleans up when it completes, but images are cached in that directory. If you use Singularity and are running up against your quota, you may consider specifying a custom cache directory via the SINGULARITY_CACHEDIR environment variable:

1
2
# In this example, we assume that the user has some storage space in the general access scratch volume
SINGULARITY_CACHEDIR=/gpfs/research/scratch/USERNAME/

More information on specifying a custom cache directory can be found at the official Singularity documentation.

Building containers and comprehensive tutorial#

For a comprehensive tutorial on Singularity, refer to this excellent guide.

Last update: July 7, 2023