Skip to content

Docker

What is Docker ?

Docker is an open-source platform that automates the deployment, scaling, and management of applications within containers. Containers allow you to package up an application with all the parts it needs, such as libraries and other dependencies, and ship it all out as one package. This guarantees that the application will run on any other Linux machine regardless of any customized settings or configurations that machine might have.

On our cluster, we run our experiments within Docker containers, to ensure they run with the correct versions of all the libraries and dependencies they require. So when submitting a job to the cluster, you will need to specify which container image you want to use to run your experiment.

We maintain a Docker registry that includes a base Docker container image. We strongly recommend using this base container image directly or deriving from it to minimize the disk size footprint and the download time of the container image to a SOL node. Container images are built layer by layer, and by deriving from an existing container image, only your custom layers need to be downloaded if the parent container image layer is already present on the node.

You can browse all available Docker container images on the Docker Registry.

How to use DIAG base container images

The DIAG base container image is built on Ubuntu 18.04 and comes with pre-installed software like ASAP, as well as basic Python packages including TensorFlow and PyTorch.

The latest version (as of June 2023) is: doduo1.umcn.nl/uokbaseimage/diag:tf2.12-pt2.0-v1

This container image contains the source code of the pathology common libraries in /home/user/source:

  • diag-models
  • pathology-anonymize
  • pathology-common
  • pathology-fast-inference

ASAP is installed in /opt/ASAP/bin. The default username and password in the container image are 'user'.

A very useful Bash command is: exec "${@}". This executes the given parameters as a command (similar to the DIAG base container image's run.sh script).

Entrypoints

ENTRYPOINT is one of the many instructions you can write in a Dockerfile. The ENTRYPOINT instruction is used to configure the executables that will always run after the container is initiated. The DIAG base container images have an ENTRYPOINT, usually a shell script, which is executed when the container is started. This script is located at /root/run.sh.

The script used as ENTRYPOINT basically initialise the environment for you and checks for additional commands to execute, if there aren't, it initialise a jupyter environment. If you need to install additional packages which are not contained on the default DIAG base container you have two options:

  • Wrap all the pip3 install in a bash script and pass it as additional parameter when running a job.
  • Create your own container image.

You can also pass parameters to container images, which are interpreted as a command to execute. For example, you could call your Python or Bash script on Chansey/Blissey by appending sbatch <your_script_path> to the container's command.

Creating your own container image

If your workflow requires extensive changes to the environment, or if you want to bundle your algorithm, you can create your container image by reusing the DIAG base container image. The steps include building a container image, testing it, and then pushing it to the Docker registry.

First create a directory (somewhere on Chansey or Blissey) and a file name Dockerfile. All resources required for the docker need to be in this directory. Here is an example of a Dockerfile:

### Derive from the base container image
FROM doduo1.umcn.nl/uokbaseimage/diag:tf2.12-pt2.0-v1

### Define a variable for the code source directory
ARG CODE_DIR="/home/user/source"

### Optionally delete obsolete code
RUN rm --recursive ${CODE_DIR}/<to-delete>

### Copy your code to the container image
COPY <your-code> ${CODE_DIR}

### Add ASAP and your code to the python path
ENV PYTHONPATH "${PYTHONPATH}:${CODE_DIR}:/opt/ASAP/bin:${CODE_DIR}/<your-code>"

### Install python packages
RUN pip3 install <your-python-packages>

#### Configure the entry point
USER root
COPY run.sh /root/
ENTRYPOINT ["/bin/bash", "/root/run.sh"]

Build and upload your container image

You should preferably try to build your container image on and upload it from your own Laptop. In the case this is a problem, you can also build and upload your container image from a virtual machine on the cluster.

If you want to use the virtual machine, you have to connect to dlc-ducklett via:

ssh diag@dlc-ducklett.umcn.nl

The password is the regular password for the cluster.

Define your container image tag

Define your container image tag as a variable:

tag=doduo1.umcn.nl/<your-name>/<docker-image-name>:<version>

Build your container image

Navigate towards the folder where your Dockerfile is located. On dlc-ducklett, the shares are mounted under /data/ (e.g. /data/bodyct/ or /data/pathology/). Build your container image with Docker:

docker build . --tag $tag

Test your container image

You can test your container image by using docker run. --rm ensures the memory is cleared after running. -v is used for volume mounting. It tells the orchestrator to link the directory /data/pathology from the machine that is running enroot (the host), to the directory /data/pathology within the container instance. You can replace the first directory with your local path to Chansey or Blissey.

After your statement, you can enter any parameters required by the entrypoint (e.g. bash <your-script> or a python file):

docker run --rm -v /data/pathology/:/data/pathology/ $tag --<parameters>=<values>

Upload your container image

Upload your container image to the Docker registry, so all machines can find it. If not pushed, dlc-ducklett will remove your built container image after 7 days.

docker push $tag

Using conda (or mamba) in your container

The DIAG base container image uses pip, but you might want to replicate your or someone elses conda environments (btw. I recommend using mamba with conda for fast dependency resolution). Then you will need to copy the exported conda environment config to the docker directory, install conda in the Dockerfile and import the conda environment:

When using mamba:

RUN wget --progress=dot:mega https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-Linux-x86_64.sh -O Mambaforge-Linux-x86_64.sh \
        && chmod +x Mambaforge-Linux-x86_64.sh && bash ./Mambaforge-Linux-x86_64.sh -b -p /home/user/conda \
        && rm -f Mambaforge-Linux-x86_64.sh # add conda to the path
ENV PATH /home/user/conda/bin:$PATH

# Update configure files
RUN echo 'export PATH=/home/user/conda/bin:$PATH' >> /etc/profile.d/pynn.sh \
        && ln -sf /home/user/conda/etc/profile.d/conda.sh /etc/profile.d/
ARG CENV="conda_cart_env37n_tf-cpu_28_07_21.yaml"
COPY <your_conda_config.yaml>​​ ${​CODE_DIR}RUN mamba env create -f ${​CODE_DIR}​​​​​​​​​​​​​​​/<your_conda_config.yaml>​​ \
    mamba clean --all --yes

When using conda:

### install miniconda
RUN wget --progress=dot:mega https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh \
        && chmod +x miniconda.sh && ./miniconda.sh -b -p /home/user/conda \
        && rm -f miniconda.sh

# add conda to the path
ENV PATH /home/user/conda/bin:$PATH

# Update configure files
RUN echo 'export PATH=/home/user/conda/bin:$PATH' >> /etc/profile.d/pynn.sh \
        && ln -sf /home/user/conda/etc/profile.d/conda.sh /etc/profile.d/

ARG CENV="conda_cart_env37n_tf-cpu_28_07_21.yaml"
COPY <your_conda_config.yaml>​​ ${​​​​​​​​​​​​​​​​​​​​​​​CODE_DIR}RUN conda env create -f ${​CODE_DIR}​/<your_conda_config.yaml>​​

Then, you need to conda activate your environment, e.g. in the .bashrc or .bash_aliases in the docker (or in your job script):

source /home/user/conda/etc/profile.d/conda.sh
conda activate <your-env-name>

Tip: conda gets very slow when installing new packages in big environments, I recommend using mamba (without it I would have given up on conda).