Singularity 2016

Introduction

Singularity is a portable application stack packaging and runtime utility. With Singularity, you can provide whole working environments and install the OS, and software you need to use within a container. In the best case, "this means that you don’t have to ask your cluster admin to install anything for you - you can put it in a Singularity container and run."[¹ http://singularity.lbl.gov/]

Installed version

The currently installed version is available on environment hpc-env/6.4

Singularity/2.4.2-GCCcore-6.4.0
Singularity/2.6.1-GCCcore-6.4.0 (D)

Using Singularity

Singularity can be a very powerful tool to create containers with your favoured OS environment, and all the tools you need - completely without the help or permission of the HPC administrators. In order to use Singularity, you need to create your own containers on a local device since you need root permissions to do so which we can't grant our users on our cluster. In the following chapters, we will show you exemplarily how to create your own containers, fill them with the software you need, and how to use them to start your computations. But first, Singularity must be installed on a local system.

Installation

In our example, we use CentOS 7. For other distributions, the procedure should be similar, but some steps might slightly differ, especially the needed dependencies for the installation.

To install Singularity on your system, you need to install at least two dependencies , clone the GitHub repository and perform confingure/make/make install. To make this as simple as possible, open a terminal, and copy-paste this lines:

cd ~ && mkdir singularity_install && cd singularity_install
sudo yum -y install libarchive-devel squashfs-tools
git clone https://github.com/singularityware/singularity.git
cd singularity
git fetch --all
git checkout 2.6.1
./autogen.sh
./configure --prefix=/usr/local
make
sudo make install

Now, Singularity should be installed on your system. Just to be sure, check the version of the newly installed software:

singularity --version

Singularity should display the installed version.
Should this be the case, you can remove the folder containing the source files we originally needed for the installation.

Creating Containers

There are three ways to create containers:

• A) Downloading solely OS containers and manually adding software packets
• B) Creating installaton scripts, including OS and post-install commands
• C) Searching for 'ready to go scripts' from Singularitys repository

Below we will briefly cover each of the methods mentioned.

A) Download and modify

Always remember: The following commands must be executed on your own local machine!
To download an image only containing CentOS, type in the following command:

sudo singularity build --sandbox centos7.img docker://centos:7

Now, switch into the container environment and install the packets needed:

sudo singularity shell --writable centos7.img
# Now, every shell command will be forwarded to the container centos.img
yum update -y
yum install vim -y
# To escape from the container shell, type in:
exit

In this example, we switched to the containers shell, installed the text editor vim, and finally exited from the containers shell with exit.

When you finished modifying the image, create a read-only image file for the productive use (which additionally makes is quite more space efficient):

sudo singularity build centos7.simg centos7.img

Singularity will automatically bind your $HOME directory so that you can enter your filesvfrom within the container. If you need other paths to be connected to your container, you can can do this with the --bind command:

singularity shell --bind $WORK centos7.simg

B) Working with your own recipe (Bootstrapping)

By creating a personal recipy (also called definition file = .def), you have the advantages of creating your personal environment, chosing the OS and installing the software that fits your needs perfectly. When the recipe is created, a new container can be bootstrapped with one single command at any time.

Start by creating a script file, e.g. with the vim editor...

vim my_container.def

... and fill it with the settings you prefer:

# Chose an OS, preferably from the official docker images
Bootstrap: docker
From: centos:latest
# Run post-install commands. Use them just like you would do within the targeted operating system

# Set environment variables
%environment
PATH=new/directory:$PATH

# Set labels 
%labels
AUTHOR Monika Testuser, monika.testuser@uol.de

%post
yum -y update && yum -y install wget vim

# Copy files into the container.
%files
source/path/to/file.txt target/path/to/file.txt

After saving and closing the file, you start the installation with:

sudo singularity build --sandbox my_container.img my_container.def

Afterwards, you can modify the newly built image like shown on A)

sudo singularity shell --writable my_container.img
touch testfile.txt
exit

Like in A), create a read-only image file when you finished modifying the image:

sudo singularity build my_container.simg my_container.img

C) Use an 'off-the-shelf' image

On the Singularity Hub, you have access to a lot of pre-puilt images and the corresponting recipes.

Here, we have two options: A) Downloading the complete image files or B) downloading the corresponding recipe. For downloading the ready-to-use image, Singularity brings a pull function.

# Pulling a tensorflow image from the singularity hub:
singularity pull shub://marcc-hpc/tensorflow

This command will download a read-only image file. You use it to start calculations but you can't change or modify it any more. Should you need to do any changes, consider using the recipe. On the project site of tensorflow (for example), you can download the recipe for every container image. When downloaded, the recipe can be extended by any desired argument and be build as --writable or --sandbox.

https://singularity-hub.org/containers/2725/download/recipe

Like in A) and B, finalize your image into a .simg file when you are done modifying.

Transferring your Container to CARL/ERLE

If your container is ready for computing and finalized by building into a .simg file, you will probably want to transfer it to the cluster (CARL or EDDIE). For this task, we can use the tool scp, which should be pre installed on every common linux distribution. The usage is very straightforward:

scp <container_file> abcd1234>@carl.hpc.uni-oldenburg.de:/home/abcd1234/
# Where abcd1234 should be your domain user name.

Troubleshooting

sudo: singularity: command not found
If this error occurs on your local machine, sudo may be missing a path to Singularitys installation directory. With sudo visodu this can be changed by adding the path to a specific line:

Just add :/usr/local/bin to the line containing secure_path so it looks like this:
Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin

Putting in Practice

Now, we will show you how to use Singularity from the first step to the last command. Let's say, we want to convert a video file into a different type: .flv to 'mp4 because .flv files can't be handled by many video players. We already stored our beloved jellyfish clip in our HPCs Download directory:

#on CARL/ERLE:
cd ~/Downloads
wget http://mirrors.standaloneinstaller.com/video-sample/jellyfish-25-mbps-hd-hevc.flv

We choose HandBrakeCLI as our converting tool. Since converting files can be very compute intensive, we decide to use the HPC Cluster. The only problem is, that HandBrakeCLI is not available as a loadable module. This is where Singularity comes in handy.
After we installed Singularity, we ware ready to go:
On our local machine, we create an image by writing a definition file with vim HandBrake.def...

Bootstrap: docker
From: ubuntu:latest

%post
# install dependencies 
apt-get -y update
apt-get -y install autoconf automake build-essential cmake git libass-dev libbz2-dev libfontconfig1-dev libfreetype6-dev libfribidi-dev libharfbuzz-dev libjansson-dev liblzma-dev libmp3lame-dev libogg-dev libopus-dev libsamplerate-dev libspeex-dev libtheora-dev libtool libtool-bin libvorbis-dev libx264-dev libxml2-dev libvpx-dev m4 make nasm patch pkg-config python tar yasm zlib1g-dev libdrm-dev

# pull source files, make & install HandBrakeCLI & delete the install-dir
mkdir /handbrake-install
cd /handbrake-install
git clone https://github.com/HandBrake/HandBrake.git && cd HandBrake
./configure --launch-jobs=$(nproc) --launch --disable-gtk
make --directory=build install
cd /
rm -rf /handbrake-install

... and build the image with this recipe:

sudo singularity build HandBrake.simg HandBrake.def 

--> Since we did not need to modify anything after the building process, we skipped --sandbox and directly created a .simg file!

Let's transfer the new image to our cluster:

scp HandBrake.simg abcd1234>@carl.hpc.uni-oldenburg.de:/home/abcd1234/

At last, we can actually work with our new image.
At this point, we will use the exec command:

singularity exec HandBrake.simg HandBrakeCLI -i ~/Downloads/jellyfish-25-mbps-hd-hevc.flv -o ~/Downloads/jellyfish-25-mbps-hd-hevc.mp4

And that's it! We used the exec command to call the containerized HandBrakeCLI and processed the file outside of the container. This is possible, since Singularity automatically binds your $HOME path.

Documentation

For further information developers offer a detailed website with further information, and a Quick Stard Guide.