How to convert docker images into Singularity's native format

Singularity offers interoperability with Docker images . Here are provided different ways to convert images from the Docker format to singularities.

  • Local Docker Image: If the image is already pulled/cached by Docker just use the following command to create a .sif container .

    sudo singularity build <NAME_OF_SINGULARITY_CONTAINER>.sif docker-daemon://<NAME_OF_DOCKER_IMAGE>:<IMAGE_TAG> # General format
    sudo singularity build lent_latest.sif docker-daemon://lent_image:latest                                      # Example building from 'lent_image:latest'

    This will create in the current working directory a file with the .sif extension, which is the native format Singularity uses.

  • Docker repository: If the image is available on Docker Hub or any other registry (private or public) it can be pulled by Singularity and turned into it’s native format automatically.

        sudo singularity pull docker://<NAME_OF_DOCKER_IMAGE>                # Docker Hub
        sudo singularity pull docker://<registry>/<user>/<repo-name>[:<tag>] # General format to pull from any other repository
  • Definition file: This looks a lot like a Dockerfile and provides a recipe for creating a Singularity container. Below is provided an example definition file (Official Docs):

        # Example 1: Using private docker registry
        Bootstrap: docker # Use a docker registry               # Specifies method.
        From: <registry>/<namespace>/<container>:<tag>@<digest> # General form
        Registry: http://custom_registry                        # Optional, if using a custom registry then it must be used to specify.
        # Example 2: Using local Singularity container
        Bootstrap: library
        From: <path-to-container>:<tag>
        # 'files' is used to copy files/folders from the host system to the container.
            /file1 /opt
        # 'environment' is used to set up environment variables
            export LISTEN_PORT=12345
            export LC_ALL=C
        # 'post' is a series of commands that will be executed once, when 
     the container.
            apt-get update && apt-get install -y netcat
            echo "export NOW=\"${NOW}\"" >> $SINGULARITY_ENVIRONMENT
        # 'runscript' are commands that will execute every time container starts with the 'run' command.
            echo "Container was created $NOW"
            echo "Arguments received: $*"
            exec echo "$@"

    Definition files does not allow to create a Singularity container from a local Docker image, but only from a running container. If you want to use Docker images, there have to be saved in a registry.

    It is advised to use the Definition file, even if it contains nothing more than a local image, and in the %post section to change permission rights of folders like /opt to 775 or 777 so that you are able to write inside these folders in the cluster, as a non-sudoer (chmod -R 775 /opt/).

See also