Introduction to Singularity Containers

Northwestern IT Research Computing Services

Matthew Rich

m-rich@northwestern.edu

(Or just look me up in the NU Directory)

Pre-Containers

Process isolation (for security)

Namespaces (better abstraction)

Containers

Process isolation AND Namespacing

And dependency packaging!

Docker was announced in 2013.

Docker offered relatively easy to use tools and better filesystem isolation.

The Docker ecosystem

Image repositories: Docker Hub, Biocontainers, private

Runtimes: single host, multi-host cluster, managed clusters

Standardization: image format and runtime environment

Docker vs traditional HPC

Docker runs as root!

This is a no-go for shared computing resources like Quest

Singularity

Singularity is an alternative container technology designed for traditional HPC environments.

https://sylabs.io/singularity/

Singularity gives you greater control of the runtime environment.

The running container will have exactly the environment defined in the image.

"Bind mounts" make the host's filesystem accessible inside the container.

Singularity can use your HPC's resources natively.

Singularity containers can be run like any other command in a batch job.

Singularity supports GPU hardware via the --nv flag.

MPI works seamlessly within a Singularity container (provided OpenMPI is installed).

Singularity is available on Quest!

                        $ module load singularity
                    

Getting Singularity Images

Singularity can pull images from the Docker Hub:

                    $ singularity pull ubuntu.sif docker://ubuntu
                    

This will create a singularity image file called ubuntu.sif.

Getting Singularity Images

Singularity can pull images from the Singularity Hub:

                    $ singularity pull shub://nuitrcs/biobakery
                    

https://www.singularity-hub.org/

Note: The Singularity Hub is an unsupported, community project.

Getting Singularity Images

Singularity can pull images from the Singularity Library:

                    $ singularity pull library://library/default/ubuntu:18.04
                    

https://cloud.sylabs.io/library/

Note: The Singularity Library is supported by Sylabs.

Getting Singularity Images

You can build your own Singularity images with "recipe files".

                        Bootstrap: docker
                        From: continuumio/miniconda3
                        
                        %environment
                            export LC_ALL=C
                        
                        %post
                            /opt/conda/bin/conda install pandas matplotlib
                        
                        %runscript
                            python
                    

Images cannot be built on Quest.

Sylabs Remote Builder

https://cloud.sylabs.io/builder

Sylabs provides free image hosting and building.

Paste in a def file or use singularity build --remote!

Running Singularity Containers

Run an interactive shell in a container with the shell subcommand:

                    $ singularity shell ubuntu.sif
                    Singularity: Invoking an interactive shell within container...

                    Singularity ubuntu.sif:~>
                    

Running Singularity Containers

Run the image's default command with run:

                    $ singularity run shub://nuitrcs/hello-world
                    Hello world!
                    

Running Singularity Containers

Specify the exact command to run with exec:

                    $ singularity exec docker://ubuntu cat /etc/lsb-release
                    DISTRIB_ID=Ubuntu
                    DISTRIB_RELEASE=18.04
                    DISTRIB_CODENAME=bionic
                    DISTRIB_DESCRIPTION="Ubuntu 18.04.1 LTS"
                    

Binding Directories

Singularity allows you to map directories on the host system (Quest) to directories in the container.

This lets software in a container access files on the host.

$HOME and $TMP are mapped by default.

Binding Directories

Use the -B flag to map additional directories:

                    $ singularity shell -B /projects/pXXXXX:/project ubuntu.sif
                    Singularity: Invoking an interactive shell within container...

                    Singularity ubuntu.sif:~> ls /project
                    

You have the same permissions inside the container as on the host.

Exercise 0:

SSH to the workshop server.

                        $ ssh tempuserXX@quest.northwestern.edu
                    

Exercise 1:

Pull an image from the Docker Hub.

                        $ singularity pull docker://python
                    

How big is the file in mb?

What happens if you execute the file?

Exercise 2:

Pull an ubuntu image and run a shell inside it.

                        $ singularity shell docker://ubuntu
                    

Try listing the files in your $HOME directory.

Try creating a file in your $HOME directory.

Try creating a file in /etc.

Where is the image file?

Exercise 3:

Build an image from a recipe file.

First visit https://cloud.sylabs.io/builder and generate and save auth token.

                        $ git clone https://github.com/nuitrcs/singularity-workshop.git
                        $ cd singularity-workshop/pandas-example
                        $ singularity build --remote pandas_example.sif pandas_example.def
                        $ singularity run pandas_example.sif Evanston_Arrests.csv
                    

Exercise 4:

Pull a bioinformatics image and run it.

                        $ singularity pull blast.sif docker://biocontainers/blast:2.2.31
                        $ cp /projects/w10001/data/* . # copy zebrafish.1.protein.faa and P04156.fasta to cwd
                        $ singularity exec blast.sif makeblastdb \
                            -in zebrafish.1.protein.faa -dbtype prot
                        $ singularity exec blast.sif blastp \
                            -query P04156.fasta -db zebrafish.1.protein.faa \
                            -out results.txt
                    

Exercise 5:

Submit a batch job that uses Singularity.

                        $ sbatch batch_example.sh
                    

Then watch your current working directory for the job output!

Questions?

m-rich@northwestern.edu