How to convert a Docker container to an Apptainer container

General

Docker is a software system that provides a convenient way of running software from within a preset environment with all the dependencies setup by the developers on any other Linux system. However, due to technical limitations Docker is not supported and not available on ARC.

Instead an alternative container technology based on Apptainer (former Singularity) can be used. Apptainer is another container technology with its own container format and specifications, but it can use Docker containers as a source and convert them in its native Apptainer format.

Examples

Converting a GATK Docker image

GATK is a popular bioinformatics toolbox. To find a container for the latest version of we have to go to its home page at

https://www.broadinstitute.org/gatk/

Then we navigate to the download section following the Download latest version of GATK link.

https://github.com/broadinstitute/gatk/releases

There we find a link

Docker image: https://hub.docker.com/r/broadinstitute/gatk/

which leads us to the DockerHub site, that hosts publicly available images.

On that page we find out that the docker image is called broadinstitute/gatk. This is all information we need to convert it to an Apptainer image.

The build process will require some storage space and some amount of RAM. In some cases this may be an obstacle that will have to be solved.

• So, we have to change the working directory to a location which we want to use for the image and that has enough space to hold the image and the temporary files.

$ cd my_images

• Now we can check if apptainer is available:

$ apptainer --version

apptainer version 1.1.4-2.el8

• Convert the Docker imagebroadinstitute/gatk to a new Apptainer image gatk.sif:

$ apptainer build gatk.sif docker://broadinstitute/gatk

INFO:    Starting build...
Getting image source signatures
Copying blob 53d8c492d3e6 done  
Copying config 17075ce1d9 done  
Writing manifest to image destination
Storing signatures
2023/02/13 14:22:04  info unpack layer: sha256:53d8c492d3e6c2d88e40ff11d3c606a6ede7e61b2c11541e3b721c52b8410026
INFO:    Creating SIF file...
INFO:    Build complete: gatk.sif

$ ls -lh

-rwxr-xr-x 1 username username 1.7G Feb 13 14:49 gatk.sif

This takes about 5 minutes.

• Test the image:

$ apptainer run gatk.sif gatk --help

INFO:    underlay of /etc/localtime required more than 50 (94) bind mounts

 Usage template for all tools (uses --spark-runner LOCAL when used with a Spark tool)
    gatk AnyTool toolArgs

 Usage template for Spark tools (will NOT work on non-Spark tools)
    gatk SparkTool toolArgs  [ -- --spark-runner <LOCAL | SPARK | GCS> sparkArgs ]
....
....

Done!

Please note, the different software can be setup differently by different developers who crated the original container. Therefore, the way how software is run from within a container may differ, and differ significantly. You have to read the information about the container to find out how to use it properly.

At this point

• The container can be moved to a different location for convenience of use.
• It can also be shared with other people,
• It can be moved to a different Linux system.
• It is expected to work the same way on most Linux systems.

Links

How-Tos