Installation Quick Start

git clone https://github.com/singularityware/singularity.git
cd singularity
./autogen.sh
./configure --prefix=/usr/local
make
sudo make install

Command Quick Start

Make a container

singularity create centos7.img
Initializing Singularity image subsystem
Opening image file: centos7.img
Creating 768MiB image
Binding image to loop
Creating file system within image
Image is done: centos7.img

Dump docker layers into it! Nope, you don’t need sudo.

singularity import centos7.img docker://centos:7
Cache folder set to /home/vanessa/.singularity/docker
Importing: base Singularity environment
Importing: /home/vanessa/.singularity/docker/sha256:785fe1d06b2d42874d3e18fb0747ad8c9ed83d04e7641279a4d5ae353f27eff9.tar.gz
Importing: /home/vanessa/.singularity/docker/sha256:a90ac515821d5b70fe202c201485396ba95305348f9f7f52813e2873d3c72eee.tar.gz

Shell into container

singularity shell centos7.img
Singularity: Invoking an interactive shell within container...

# I am the same user inside as outside!
Singularity centos7.img:~/Desktop> whoami
vanessa

Singularity centos7.img:~/Desktop> id
uid=1000(vanessa) gid=1000(vanessa) groups=1000(vanessa),4(adm),24,27,30(tape),46,113,128,999(input)

Want to keep the container’s environment contained, meaning no sharing of host environment?

singularity shell --contain centos7.img

Writing in the container

By default, containers run in read only. While we discourage making tweaks on the fly to containers (you should properly define all edits to the container in a boostrap specification file, shown later) you can add --writable to any command to write inside the container. Let’s make a directory. This command must be done with sudo.

sudo singularity shell --writable centos7.img
Singularity centos7.img:/root> mkdir /data
Singularity centos7.img:/root> touch /data/noodles.txt
exit

Executing Commands

Singularity exec will send a custom command for the container to run, anything that you like! Unlike docker exec, the container doesn’t have to be actively running. So, to list the /data folder we just bound, we could do the following:

# Did the directory persist?
singularity exec centos7.img ls /data
noodles.txt

Working with Files

Files on the host can be reachable from within the container

echo "Hello World" > /home/vanessa/Desktop/hello-kitty.txt
singularity exec centos7.img cat /home/vanessa/Desktop/hello-kitty.txt
Hello World

By default, most configurations will mount /tmp and the home directories by default. On a research cluster, you probably want to access locations with big datasets, and then write results too. For this, you will want to bind a folder to the container. Here, we are binding my Desktop to the data folder, and listing the contents to show it worked. We use the command -B or --bind to do this.

$ singularity exec --bind /home/vanessa/Desktop:/data centos7.img ls /data
centos7.img	     researchapps-matlab-sherlock-master.img
hello-kitty.txt      singularity-recipe-demo.mp4
party_dinosaur.gif

Bootstrap Recipes

For a reproducible container, the recommended practice is to build by way of a bootstrap file. This also makes it easy to add files, environment variables, and install custom software, and still start from your bootstrap of source (e.g., Docker). Here is what a basic bootstrap file looks like for Singularity 2.3:

Bootstrap: Docker
From: ubuntu:latest

%runscript

exec echo "The runscript is the containers default runtime command!"


%files
/home/vanessa/Desktop/hello-kitty.txt /data/hello-kitty.txt
/home/vanessa/Desktop/party_dinosaur.gif /tmp/the-party-dino.gif


%environment
VARIABLE MEATBALLVALUE

%labels
AUTHOR [email protected]

%post

apt-get update && apt-get install python3 git wget
mkdir /data
echo "The post section is where you can install, and configure your container."
Edit me