— Using Singularity to create portable appliances

Red Hen makes use of HPC facilities in three locations: UCLA, Case and RRZE. To facilitate the exchange of pipelines and to minimize setup time, software that is to be run at multiple HPC centres and/or is difficult to install and/or has esoteric dependencies (e.g. old versions of libraries; libraries so large that they cannot be sensibly installed on HPC systems, etc.) can be installed within Singularity containers. The purpose of this document is to describe how to set up such a container.

1. Prerequisites

You will need a machine on which you have root rights and sufficient free space on the hard disk - 5 Gigabytes plus whatever your application needs should do for most taks - and sufficient RAM to build the software (2 Gigs is not enough for Tensorflow; 6 Gigs is). This can be a virtual machine, for which a 20 Gig hard disk is recommended.
This document assumes you are running Ubuntu 16.04 LTS.

2. Installing Singularity

Follow the instructions for Linux or for Mac. If you have Windows, you will have to use a virtual machine with Linux installed. [Todo: provide virtual machine]
At the time of writing this (Dec 2016), the GitHub version has the advantage of being better for importing Docker images. If that is not functionality you need, you can go with the release version.
Copy-Paste for this step in Linux:
VERSION=2.2 wget https://github.com/singularityware/singularity/releases/download/$VERSION/singularity-$VERSION.tar.gz tar xvf singularity-$VERSION.tar.gz cd singularity-$VERSION ./configure --prefix=/usr/local make sudo make install

Alternatively, you can install the packaged version, in Debian/Raspbian called singularity-container.

3. Creating an image

sudo singularity create --size 10000 mycontainer.img
Creates an empty image of roughly 10 Gigabytes. Note that this is a sparse file, so it will not take up as much space initially, even if it looks like it:
redhen@server:~$ sudo singularity create --size 10000 singularity_containers/mycontainer.img
Creating a new image with a maximum size of 10000MiB...
Executing image create helper
Formatting image with ext3 file system
Done.
redhen@server:~$ ls -lh singularity_containers/mycontainer.img
-rwxr-xr-x 1 root root 9,8G Dez 22 15:18 singularity_containers/mycontainer.img
redhen@server:~$ du -h singularity_containers/mycontainer.img
289M    singularity_containers/mycontainer.img
redhen@server:~$
Unfortunately, sparse files can inflate when they are being copied (use rsync, not scp) or when they are stored on NFS mounts. Thus, basically, you should expect your sparse file to end up at its full size eventually and thus avoid unneccessarily large containers.

4. Bootstrapping (i.e. "filling" an image)

To create a Debian or Ubuntu image, you have to install debootstrap:
sudo apt-get install debootstrap
Next you will have to create a Bootstrap definition. You can use the one attached to this page, which is based on an example found at the singularity webpage. The relevant parts read as follows; explanations are given in the comments:
BootStrap: debootstrap # The bootstrap command used
OSVersion: xenial # This is Ubuntu 16.04 LTS, codename Xenial Xerus
MirrorURL: http://us.archive.ubuntu.com/ubuntu/ # This is where the process can find the data needed. If you are in Europe, you can choose another mirror at https://launchpad.net/ubuntu/+archivemirrors or just use the archive provided by FAU: http://ftp.fau.de/ubuntu/

%runscript
    echo "This is what happens when you run the container..." # Replace this with the default command including all necessary options, so that running the image will directly run the software for which you built the container.

%post
# Everything in this section will be executed after bootstrapping the operating system is complete
    sed -i 's/$/ universe/' /etc/apt/sources.list # Some software is only available via the universe repository, so this will be added to apt's sources.list
    apt-get -y update # This makes sure the sources from the universe repository are loaded
    apt-get -y install nano git # Change this at your leisure. Neither of them is necessary.
   # Add all commands needed to install the software
While it is possible to install software interactively (see below), it is generally recommended to do so via the definition file to make transparent and reproducible what was actually done to arrive at the image.