How to create a Definition file for a Singularity container

A Singularity Definition File (or “def file” for short) is like a set of blueprints explaining how to build a custom container . It is similar to the Dockfile used in Docker .

Step-by-step guide

  1. First we have to define the Header part, which describes the base operating system that should be used to build the container. It should be written at the top of the def file and it is composed of several keywords. Keyword Bootstrap is used basically to tell how to get the base image . Examples are:

    1. library, where Singularity will search in the Container Library (similar registry like DockerHub hosting images).
    2. docker, where it search in the Docker Hub for the base image.
    3. localimage, where is will search in the local machine for a .sif file to use as a base image.
    4. docker-daemon, where it will search on locally running containers of Docker instead of the Docker Hub (convenient for images that are not available publicly).

      The container must be running or stopped for this bootstrap agent and you have to find the path where is container is actually stored (usually in “/var/lib/docker/containers”)

    All these bootstrap agents also need a second keyword name From which references to the path the actual container is stored.

    # BOOTSTRAP AGENTS EXAMPLES

Bootstrap: library
From: <entity>/<collection>/<container>:<tag>

Bootstrap: docker
From: redis:latest

Bootstrap: docker
From: <registry>/<container>:latest
Registry: http://custom_registry # Use if there is a private registry. Default it Docker Hub

Bootstrap: localimage
From: $HOME/Projects/lent-latest.sif

Bootstrap: docker-daemon
From: /var/lib/docker/containers/9b33a37ff242f87e98abe916bc471c4b672f4316306d82112db5206846d7c074

  2. The first step is mandatory and have to exist in every definition file. After that, we can add sections which are optional and execute commands at different times during the build process.

    1. %setup: This scriptlet is executed outside of the container on the host system itself, and is executed with elevated privileges.

    2. %files: This section allows you to copy files from your host system into the container.

      files section example:

      %files
    /etc/my_file_1 # Will copy from the host system to the /etc folder inside the container.
    my_file_2 /opt # Will copy from the CWD of the host system to the /opt folder inside the container.

    3. %post: This section is where you can setup some dependencies for the project.

      post section example:

      pacman -Syyu --noconfirm openmpi eigen gcc make flex git

    4. %test: This section runs at the very end of the build process to validate the container using a method of your choice. You can also execute this scriptlet through the container itself, using the test command.

      test section example:

      %test
    source /opt/OpenFOAM/OpenFOAM-v1806/etc/bashrc
    foamVersion &> /dev/null
   if [ "$?" == 0 ]; then
        echo "OpenFOAM check: OK"
    else
        echo "OpenFOAM check: NOT OK"
    fi

    5. %environment: This section allows you to define environment variables that will be set at runtime .

      These variables are not made available at build time.

      environment section example:

      %environment
    export LISTEN_PORT=12345

    6. %runscript: The contents of this section are written to a file within the container that is executed when the container image is run. Arguments following the container name are passed to the runscript.

      %runscript section example:

      %runscript
	echo "Container was created $NOW"
	echo "Arguments received: $*"
	exec echo "$2"

      And then by running the container we can see that:

      Executing a container with arguments:

      ./my_container.sif this that and the other
Container was created Wed March 11 13:01:56 UTC 2020
Arguments received: this that and the other
that

    7. %labels: This section is used to add metadata to the file /.singularity.d/labels.json within your container. The general format is a name-value pair. See JSON too.

      %labels section example:

      %labels
    Author ip27fuzu@stud.tu-darmstadt.de
    Version v1.0.0
    Modified Running with params X-Y-Z

See also