Build A Container

The Build Specification

Singularity Hub builds your Singularity containers from a build specification - a file named "Singularity" that is used to bootstrap a container. Singularity Hub makes this build process easy, without requiring transferring files or having sudo permissions on your part. You simply need to write a build file, put it in a Github repo, and then connect that repo to your account. Each time that you push, a new container will be generated in Singularity Hub for you to retrieve programatically from any command line. Each branch of your repo is considered a different tag of your image, and each tag can have multiple versions (commits). Let's take a look at the general workflow for doing this. Here we have a repo with a Singularity build file:

Singularity

BootStrap:docker  
From:ubuntu:latest  

%files
/home/vanessa/Desktop/rawr.sh /code/rawr.sh

%labels
MAINTAINER Vanessasaur
SPECIES Dinosaur

%environment
RAWR_BASE=/code
export RAWR_BASE

%runscript
echo "This gets run when you run the image!" 
exec /bin/bash /code/rawr.sh "$@"  

%post  
echo "This section happens once after bootstrap to build the image."  
mkdir -p /code  
apt-get install vim  
echo "Kibbles and bits, but really more bits."  

Add Tests

Singularity Hub will do a basic test to see if your container runs a command to list files. This test will return that the bootstrap is successful given a return code 0, and this is the approach that we must take to support a wide variety of containers with different OS inside. However, you can imagine cases where a container might have an otherwise working OS, but perhaps run out of room extracting some data and erroneously report as correct. For this reason, we encourage you to write your own tests for your container to be sure that everything works as you would expect. If these tests don't pass, the build will fail as you would want. On the other hand, if you want the build to appear successful so you can pull and inspect the container, you can remove these tests.

Building your Container

I would add this file to one of my Github repos, and push to Github.

git add Singularity  
git commit -m "Adding Singularity file."  
git push origin master  

Then you should log in to Singularity Hub with your Github account, and add the repository. A collection of builds, a Container Collection, is associated with a single repository.

To trigger the build, you simply need to push to your repository, and it will happen automatically. If you want different tags for an image, then simply push a new branch. If you want different versions for a tag, push the equivalent branch, and the version is the commit. The "latest" tag for your repository is always associated with the most recent commit from master. Within your container collection you have have many tags and versions, each available programatically from the command line, and for interactive viewing from the browser

Customizing and Updating your Builder

There are a few important variables that you can change the default settings for. When we update the builders on Singularity Hub (for example, when a new version is released) all new collections will use the latest builder, by default. However, collections that are already existing will not be updated automatically, as this may not be your preference. Thus, you will want to select EDIT BUILDER (see in the image above) to come to this screen:

Here you can change many options:

• Builder: By default, we use an Ubuntu 16.04 image with debootstrap and yum installed, and Singularity 2.3. You can change that in this view. We currently provide the builders, and if you find none are suitable, please submit an issue and we will figure out a solution right away!
• Build Size: By default, we estimate the size of your image by building it first into a folder, and then we add 200MB of padding. If you find errors occurring at this step, or that the size should be larger or smaller, we recommend that you use the same Edit Builder button to set the size variable. If we find a size specified by you, then we will skip the estimation step (and your build is twice as fast!).

Best Practices

We are providing this builder as a service, and would greatly appreciate the following:

• Delete old or updated builds. Keeping Singularity Hub open and free for use, without limitations, is dependent on having an affordable cost structure. We pay for every file in storage, and every build, so it is not ideal to keep files that won't be needed.
• Add more branches to generate different tags for an image. Let's say that I have an image called AnalysisGPU and I've built it for two versions. Instead of creating two repostories on Github, AnalysisGPU_version1 and AnalysisGPU_version2, if I push to a branch called version1and a second calledversion2for one repository calledAnalysisGPU, then my images will be available as AnalysisGPU:version1andAnalysisGPU:version2`