udocker allows to execute Docker containers completely in user space. Because of that, administrative functionality inside of the container is severly limited, but, that is not a problem for most HPC containers that need to run a certain application.
udocker also allows to modify Docker containers as long as the modification only involves installing or modifying files inside of the container.
Because of its simplicity, we recommend udocker to run pre-packaged Docker containers from Dockerhub or other repositories.
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
~/.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.
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:
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
--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
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