udocker

udocker setup

udocker is installed by CHPC and available by loading its module, module load udocker.

When Docker containers are run or pulled from the remote repository (e.g. Dockerhub), they are written/cached to a local directory writeable by the user, which by default is , ~/.udocker. Since containters can be large, storing many of them may exceed the 50 GB disk quota that we set by default (research groups which purchased their own home space are exempt from this quota). To keep better track of disk space used by the local container repository, we recommend to set it to a certain directory (either in home or group space) through environment variable UDOCKER_DIR, e.g. , export UDOCKER_DIR $HOME/udocker.

Running Docker containers

udocker command syntax is similar to that of Docker.

Most of our users will want to run the container as themselves, and having their home directory and scratch file spaces visible inside of the container. This is achieved with the following command:

udocker run --user=u0101881 --bindhome --volume=/scratch ubuntu

ubuntu is the container we want to run, which is available at Dockerhub (which is udocker's default repository). This command will pull the remote container layers into the local repository, and run the default command in the container - if it's absent, it will run the bash shell. To run bash explicitly, we would modify the command to

udocker run --user=u0101881 --bindhome --volume=/scratch ubuntu /bin/bash

Different repository can be specified with the --registry flag, however, the container needs to be first explicitly pulled and then run:

udocker pull --registry=https://registry.access.redhat.com rhel7
udocker run rhel

Container images available in local repository can be listed by:

udocker images

To search container images in the remote repository, use

udocker search <string_to_search_for>

If a container has mount points which are not present on CHPC, we can have to use the --novol option to ignore it. For example, to run the blastp tool from Biocontainers, we have to:

udocker run --novol /data --novol /config --user=u0101881 biocontainers/blast blastp -help

Sometimes, a version tag needs to be also added to the container name in order to be able to pull it from a given registry:

udocker pull --registry=https://quay.io quay.io/biocontainers/star:2.6.0b-0

Modifying Docker Containers

udocker also allows for limited modification of existing containers, in particular installing or modifying packages inside the container. The requirements are that the container needs to be in a local repository, and that the modification only involve files inside of the container.

To modify the system part of the container, one needs to be root inside of the container. udocker makes one a root by default, but, for bookkeeping reasons it is good to specify the root user explicitly when running the container. We strongly discourage being a root in a container since this could be a vector for priviledge escallation if the container runtime has a vulnerability. For that reason, root should be only used when absolutely necessary, e.g. to modify the container. Subsequent launches of the modified container should be done as an user inside.

For example, to install the vim text editor in a Fedora base container:

$ ./udocker create --name=myfed fedora:latest
						$ ./udocker run --user=root myfed /bin/bash
						a92387cd# yum install -y vim
						a92387cd# exit
						$ ./udocker run --user=u0101881 --bindhome myfed /bin/bash
						adba7d51$ which vim
						/usr/bin/vim

$ in this case denotes the terminal prompt. We first create local container, then get into it as root and install vim, then get into it as an user and verify that vim is available.

In Ubuntu we have to trick apt-get, as by default it' s doing some games with user IDs, by setting an additional option, e.g.:

# apt-get -o APT::Sandbox::User=root update
# apt-get -o APT::Sandbox::User=root install vim