Quick Start¶

This guide is intended for running Singularity on a computer where you have root (administrative) privileges. If you are learning about Singularity on a system where you lack root privileges, you can still complete the steps that do not require the sudo command. If you need to request an installation on your shared resource, check out our requesting an installation help page for information to send to your system administrator.

Quick Installation Steps¶

There are many ways to install Singularity but this quick start guide will only cover one. You will need git to download the source code and the appropriate tools and libraries. Create and move to a working directory and enter the following steps.

git clone https://github.com/sylabs/singularity.git

cd singularity

git fetch --all

git checkout 2.5.0

./autogen.sh

./configure --prefix=/usr/local

make

sudo make install

Singularity must be installed as root to function properly.

Overview of the Singularity Interface¶

Singularity’s command line interface allows you to build and interact with containers transparently. You can run programs inside a container as if they were running on your host system. You can easily redirect IO, use pipes, pass arguments, and access files, sockets, and ports on the host system from within a container. The --help option gives an overview of Singularity options and subcommands as follows:

$ singularity --help

USAGE: singularity [global options...] <command> [command options...] ...

GLOBAL OPTIONS:

    -d|--debug    Print debugging information

    -h|--help     Display usage summary

    -s|--silent   Only print errors

    -q|--quiet    Suppress all normal output

       --version  Show application version

    -v|--verbose  Increase verbosity +1

    -x|--sh-debug Print shell wrapper debugging information

GENERAL COMMANDS:

    help       Show additional help for a command or container

    selftest   Run some self tests for singularity install

CONTAINER USAGE COMMANDS:

    exec       Execute a command within container

    run        Launch a runscript within container

    shell      Run a Bourne shell within container

    test       Launch a testscript within container

CONTAINER MANAGEMENT COMMANDS:

    apps       List available apps within a container

    bootstrap  *Deprecated* use build instead

    build      Build a new Singularity container

    check      Perform container lint checks

    inspect    Display a container's metadata

    mount      Mount a Singularity container image

    pull       Pull a Singularity/Docker container to $PWD

COMMAND GROUPS:

    image      Container image command group

    instance   Persistent instance command group

CONTAINER USAGE OPTIONS:

    see singularity help <command>

For any additional help or support visit the Singularity

website: https://github.com/sylabs/singularity

For any additional help or support visit the Singularity website: https://www.sylabs.io/contact/ Singularity uses positional syntax (i.e. where the option is on the command line matters). Global options follow the singularity invocation and affect the way that Singularity runs any command. Then commands are passed followed by their options. For example, to pass the --debug option to the main singularity command and run Singularity with debugging messages on:

$ singularity --debug run shub://GodloveD/lolcow

And to pass the --containall option to the run command and run a Singularity image in an isolated manner:

$ singularity run --containall shub://GodloveD/lolcow

To learn more about a specific Singularity command, type one of the following:

$ singularity help <command>

$ singularity --help <command>

$ singularity -h <command>

$ singularity <command> --help

$ singularity <command> -h

Users can also write help docs specific to a container or for an internal module called an app. If those help docs exist for a particular container, you can view them like so.

$ singularity help container.simg            # See the container's help, if provided

$ singularity help --app foo container.simg  # See the help for foo, if provided

Download pre-built images¶

You can use the pull and build commands to download pre-built images from an external resource like Singularity Hub or Docker Hub. When called on a native Singularity images like those provided on Singularity Hub, pull simply downloads the image file to your system.

$ singularity pull shub://vsoch/hello-world   # pull with default name, vsoch-hello-world-master.simg

$ singularity pull --name hello.simg shub://vsoch/hello-world   # pull with custom name

Singularity images can also be pulled and named by an associated GitHub commit or content hash. You can also use pull with the docker:// uri to reference Docker images served from a registry. In this case pull does not just download an image file. Docker images are stored in layers, so pull must also combine those layers into a usable Singularity file.

$ singularity pull docker://godlovedc/lolcow  # with default name

$ singularity pull --name funny.simg docker://godlovedc/lolcow # with custom name

Pulling Docker images reduces reproducibility. If you were to pull a Docker image today and then wait six months and pull again, you are not guaranteed to get the same image. If any of the source layers has changed the image will be altered. If reproducibility is a priority for you, try building your images from Singularity Hub. You can also use the build command to download pre-built images from an external resource. When using build you must specify a name for your container like so:

$ singularity build hello-world.simg shub://vsoch/hello-world

$ singularity build lolcow.simg docker://godlovedc/lolcow

Unlike pull, build will convert your image to the latest Singularity image format after downloading it.

build is like a “Swiss Army knife” for container creation. In addition to downloading images, you can use build to create images from other images or from scratch using a recipe file <container-recipes>. You can also use build to convert an image between the 3 major container formats supported by Singularity. We discuss those image formats below in the Build images from scratch section.

Interact with images¶

Once you have an image, you can interact with it in several ways. For these examples we will use a hello-world.simg image that can be downloaded from Singularity Hub like so.

$ singularity pull --name hello-world.simg shub://vsoch/hello-world

Shell¶

The shell command allows you to spawn a new shell within your container and interact with it as though it were a small virtual machine.

$ singularity shell hello-world.simg

Singularity: Invoking an interactive shell within container...

# I am the same user inside as outside!

Singularity hello-world.simg:~/Desktop> whoami

vanessa

Singularity hello-world.simg:~/Desktop> id

uid=1000(vanessa) gid=1000(vanessa) groups=1000(vanessa),4(adm),24,27,30(tape),46,113,128,999(input)

shell also works with the shub:// and docker:// URIs. This creates an ephemeral container that disappears when the shell is exited.

$ singularity shell shub://vsoch/hello-world

Executing Commands¶

The exec command allows you to execute a custom command within a container by specifying the image file. For instance, to list the root (/) of our hello-world.simg image, we could do the following:

$ singularity exec hello-world.simg ls /

anaconda-post.log  etc   lib64       mnt   root  singularity  tmp

bin        home  lost+found  opt   run   srv          usr

dev        lib   media       proc  sbin  sys          var

exec also works with the shub:// and docker:// URIs. This creates an ephemeral container that executes a command and disappears.

$ singularity exec shub://singularityhub/ubuntu cat /etc/os-release

Running a container¶

Singularity containers contain runscripts. These are user defined scripts that define the actions a container should perform when someone runs it. The runscript can be triggered with the run command, or simply by calling the container as though it were an executable.

$ singularity run hello-world.simg

$ ./hello-world.simg

run also works with shub:// and docker:// URIs. This creates an ephemeral container that runs and then disappears.

$ singularity run shub://GodloveD/lolcow

Working with Files¶

Files on the host are reachable from within the container.

$ echo "Hello World" > $HOME/hello-kitty.txt

$ singularity exec vsoch-hello-world-master.simg cat $HOME/hello-kitty.txt

Hello World

This example works because hello-kitty.txt exists in the user’s home directory. By default singularity bind mounts /home/$USER, /tmp, and $PWD into your container at runtime. You can specify additional directories to bind mount into your container with the - -bind option. In this example, the data directory on the host system is bind mounted to the /mnt directory inside the container.

$ echo "I am your father" >/data/vader.sez

$ ~/sing-dev/bin/singularity exec --bind /data:/mnt hello-world.simg cat /mnt/vader.sez

I am your father

Build images from scratch¶

As of Singularity v2.4 by default build produces immutable images in the squashfs file format. This ensures reproducible and verifiable images. However, during testing and debugging you may want an image format that is writable. This way you can shell into the image and install software and dependencies until you are satisfied that your container will fulfill your needs. For these scenarios, Singularity supports two other image formats: a sandbox format (which is really just a chroot directory), and a writable format (the ext3 file system that was used in Singularity versions less than 2.4).

For more details about the different build options and best practices, read about the singularity flow.

Sandbox Directory¶

To build into a sandbox (container in a directory) use the build --sandbox command and option:

$ sudo singularity build --sandbox ubuntu/ docker://ubuntu

This command creates a directory called ubuntu/ with an entire Ubuntu Operating System and some Singularity metadata in your current working directory. You can use commands like shell, exec , and run with this directory just as you would with a Singularity image. You can also write files to this directory from within a Singularity session (provided you have the permissions to do so). These files will be ephemeral and will disappear when the container is finished executing. However if you use the --writable option the changes will be saved into your directory so that you can use them the next time you use your container.

Writable Image¶

If you prefer to have a writable image file, you can build a container with the --writable option.

$ sudo singularity build --writable ubuntu.img docker://ubuntu

This produces an image that is writable with an ext3 file system. Unlike the sandbox, it is a single image file. Also by convention this file name has an “.img” extension instead of “.simg” . When you want to alter your image, you can use commands like shell, exec, run, with the --writable option. Because of permission issues it may be necessary to execute the container as root to modify it.

$ sudo singularity shell --writable ubuntu.img

Converting images from one format to another¶

The build command allows you to build a container from an existing container. This means that you can use it to convert a container from one format to another. For instance, if you have already created a sandbox (directory) and want to convert it to the default immutable image format (squashfs) you can do so:

$ singularity build new-squashfs sandbox

Doing so may break reproducibility if you have altered your sandbox outside of the context of a recipe file, so you are advised to exercise care. You can use build to convert containers to and from writable, sandbox, and default (squashfs) file formats via any of the six possible combinations.

Singularity Recipes¶

For a reproducible, production-quality container, we recommend that you build a container with the default (squashfs) file format using a Singularity recipe file. This also makes it easy to add files, environment variables, and install custom software, and still start from your base of choice (e.g., Singularity Hub). A recipe file has a header and a body. The header determines what kind of base container to begin with, and the body is further divided into sections (called scriptlets) that do things like install software, setup the environment, and copy files into the container from the host system. Here is an example of a recipe file:

Bootstrap: shub

From: singularityhub/ubuntu

%runscript

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

%files

   /home/vanessa/Desktop/hello-kitty.txt        # copied to root of container

   /home/vanessa/Desktop/party_dinosaur.gif     /opt/the-party-dino.gif #

%environment

    VARIABLE=MEATBALLVALUE

    export VARIABLE

%labels

   AUTHOR vsochat@stanford.edu

%post

    apt-get update && apt-get -y install python3 git wget

    mkdir /data

    echo "The post section is where you can install, and configure your container."

To build a container from this definition file (assuming it is a file named Singularity), you would call build like so:

$ sudo singularity build ubuntu.simg Singularity

In this example, the header tells singularity to use a base Ubuntu image from Singularity Hub. The %runscript section defines actions for the container to take when it is executed (in this case a simple message). The %files section copies some files into the container from the host system at build time. The %environment section defines some environment variables that will be available to the container at runtime. The %labels section allows for custom metadata to be added to the container. And finally the %post section executes within the container at build time after the base OS has been installed. The %post section is therefore the place to perform installations of custom apps. This is a very small example of the things that you can do with a recipe file . In addition to building a container from Singularity Hub, you can start with base images from Docker Hub, use images directly from official repositories such as Ubuntu, Debian, CentOS, Arch, and BusyBox, use an existing container on your host system as a base, or even take a snapshot of the host system itself and use that as a base image. If you want to build Singularity images without having singularity installed in a build environment, you can build images using Singularity Hub instead. If you want a more detailed rundown and examples for different build options, see our singularity flow page.