How to use a Docker container on the ULHPC

How to use a Docker container on the ULHPC

First of all, Docker containers all not directly supported on the ULPHPC.
However, Singularity containers are supported and they can be built directly from (almost) any existing Docker container or Dockerfile.

From Docker Hub

In this knowledge nugget, we will use HUMAnN v3 from Biobakery as an example. The list of available version can be found here. At the time of the writing, latest available version was 3.1.1.

# Request an interactive session for 2h
si -t120
# Load the singularity module
module load tools/Singularity
# Build the Singularity container from the Docker container
# The docker pull command is docker pull biobakery/humann:3.1.1
# This should be adapted as follows for singularity:
singularity build humann3.sif docker://biobakery/humann:3.1.1

After the successful building of the container, you should now have a file named humann3.sif on your user folder. You can ensure that it works via the following command:

# The following command runs the humann program inside the container
# and request the display of its version
singularity run humann3.sif humann --version

If everything went successfully, you should see the following output:

humann v3.1.1

From a locally-built Docker container

If you already have a Docker container on your local machine that you want to convert to a Singularity container, you can do this via the following command:

# The following command assumes that you have HUMAnN v3.1.1 
# as a Docker container on your local machine.
# You can check what you have installed via the `docker images` command
sudo singularity build humann.sif docker-daemon://biobakery/humann:3.1.1

From a Dockerfile

You can also build a Singularity container from the Dockerfile, i.e. the recipe detailling how to build a Docker container. What you need to do is as follows:

  • Convert the Dockerfile into a Singularity definition file. This can be done via a Python module.
  • Build the Singularity container based on the definition file

Install spython

As a prerequisite, you need to install the spython module:

pip install spython

Create the container definition

The conversion of an existing Dockerfile can be done as follows:

# print in the console (optional)
spython recipe Dockerfile

# save in the *.def file
spython recipe Dockerfile &> singularity.def

Build the container

The final step is to build the container based on the definition file:

# You need to be root to build your container that way
# This means that you cannot do it on the HPC 
sudo singularity build your-container.sif singularity.def