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: 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:

          /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:

          source /opt/OpenFOAM/OpenFOAM-v1806/etc/bashrc
          foamVersion &> /dev/null
         if [ "$?" == 0 ]; then
              echo "OpenFOAM check: OK"
              echo "OpenFOAM check: NOT OK"
    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:

          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:

          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
    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:

          Version v1.0.0
          Modified Running with params X-Y-Z

See also