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