From the Docker website: "A container image is a lightweight, stand-alone, executable package of a piece of software that includes everything needed to run it: code, runtime, system tools, system libraries, settings."
This document will describe how to run Docker and Singularity containers on the Owens and Pitzer. You can use containers from Docker Hub, Sylabs Cloud, or any other source. As examples we will use
hello-world from Singularity Hub and
ubuntu from Docker Hub.
- Access a container
- Run a container
- File system access
- GPU usage within a container
- Build a container
The most up-to-date help on Apptainer/Singularity comes from the command itself.
User guides and examples can be found in Apptainer documents.
Setting up your environment for Apptainer/Singularity usage
No setup is required. You can use Apptainer/Singularity directly on all clusters.
A Singularity container is a single file with a
You can simply download ("pull") a container from a hub. Popular hubs are Docker Hub and Singularity Hub. You can go there and search if they have a container that meets your needs. Docker Hub has more containers and may be more up to date but supports a much wider community than just HPC. Singularity Hub is for HPC, but the number of available containers are fewer. Additionally there are domain and vendor repositories such as biocontainers and NVIDIA HPC containers that may have relevant containers.
Pull a container from hubs
Pull from the 7.2.0 branch of the gcc repository on Docker Hub. The 7.2.0 is called a tag.
singularity pull docker://gcc:7.2.0
Pull an Ubuntu container from Docker Hub.
singularity pull docker://ubuntu:18.04
singularityhub/hello-world ontainer from the Singularity hub. Since no tag is specified it pulls from the master branch of the repository.
singularity pull shub://singularityhub/hello-world
Downloading containers from the hubs is not the only way to get one. You can, for example get a copy from your colleague's computer or directory. If you would like to create your own container you can start from the user guide below. If you have any questions, please contact OSC Help.
There are four ways to run a container under Apptainer/Singularity.
You can do this either in a batch job or on a login node.
If unsure about the amount of memory that a singularity process will require, then be sure to request an entire node for the job. It is common for singularity jobs to be killed by the OOM killer because of using too much RAM.
We note that the operating system on Owens is Red Hat:
[owens-login01]$ cat /etc/os-release NAME="Red Hat Enterprise Linux Server" VERSION="7.5 (Maipo)" ID="rhel" [..more..]
In the examples below we will often check the operating system to show that we are really inside a container.
Run container like a native command
If you simply run the container image it will execute the container’s runscript.
Note that this container returns you to your native OS after you run it.
[owens-login01]$ ./hello-world_latest.sif Tacotacotaco
Use the “run” sub-command
The Singularity “run” sub-command does the same thing as running a container directly as described above. That is, it executes the container’s runscript.
Example: Run a container from a local file
[owens-login01]$ singularity run hello-world_latest.sif Tacotacotaco
Example: Run a container from a hub without explicitly downloading it
[owens-login01]$ singularity run shub://singularityhub/hello-world INFO: Downloading shub image Progress |===================================| 100.0% Tacotacotaco
Use the “exec” sub-command
The Singularity “exec” sub-command lets you execute an arbitrary command within your container instead of just the runscript.
Example: Find out what operating system the
singularityhub/hello-world container uses
[owens-login01]$ singularity exec hello-world_latest.sif cat /etc/os-release NAME="Ubuntu" VERSION="14.04.5 LTS, Trusty Tahr" ID=ubuntu [..more..]
Use the “shell” sub-command
The Singularity “shell” sub-command invokes an interactive shell within a container.
Example: Run an Ubuntu shell. Note the “Singularity” prompt within the shell.
[owens-login01 ~]$ singularity shell ubuntu_18.04.sif Singularity ubuntu_18.04.sif:~> cat /etc/os-release NAME="Ubuntu" VERSION="18.04 LTS (Bionic Beaver)" ID=ubuntu [.. more ..] Singularity ubuntu_18.04.sif:~> exit exit
When you use a container you run within the container’s environment. The directories available to you by default from the host environment are
- your home directory
- working directory (directory you were in when you ran the container)
You can review our Available File Systems page for more details about our file system access policy.
If you run the container within a job you will have the usual access to the
$PFSDIR environment variable with adding node attribute "
pfsdir" in the job request (
--gres=pfsdir). You can access most of our file systems from a container without any special treatment.
If you have a GPU-enabled container you can easily run it on Owens or Pitzer just by adding the
--nv flag to the singularity exec or run command. The example below comes from the "exec" command section of Singularity User Guide. It runs a TensorFlow example using a GPU on Owens. (Output has been omitted from the example for brevity.)
[owens-login01]$ sinteractive -n 28 -g 1
git clone https://github.com/tensorflow/models.git
singularity exec --nv docker://tensorflow/tensorflow:latest-gpu \ python ./models/tutorials/image/mnist/convolutional.py
In some cases it may be necessary to bind the CUDA_HOME path and add
$CUDA_HOME/lib64 to the shared library search path:
[owens-login01]$ sinteractive -n 28 -g 1
module load cuda [o0756]$ export APPTAINER_BINDPATH=$CUDA_HOME [o0756]$ export APPTAINERENV_LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CUDA_HOME/lib64
singularity exec --nv my_container mycmd
If you want to create or modify a container, you need root-like privilege on any OSC system. Alternatively you can create a container on a hub or a local computer then pull/upload it to OSC system.