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.
    %files
        /file1
        /file1 /opt
       
    # 'environment' is used to set up environment variables
    %environment
        export LISTEN_PORT=12345
        export LC_ALL=C
       
    # 'post' is a series of commands that will be executed once, when 
building
 the container.
    %post
        apt-get update && apt-get install -y netcat
        NOW=`date`
        echo "export NOW=\"${NOW}\"" >> $SINGULARITY_ENVIRONMENT
       
    # 'runscript' are commands that will execute every time container starts with the 'run' command.
    %runscript
        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