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
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
--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
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 firstname.lastname@example.org %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."