Build and deploy your own Docker images

It may happen that the standard profiles do not contain the packages you need. To provide your own packages in the form of your own Docker image, the following four steps are necessary:

  1. Install the Docker software locally
  2. Create a Dockerfile
  3. Build the Docker image
  4. Select a container registry and upload the Docker image

 

Install Docker

With the help of Docker, you can run applications in so-called containers. The big advantage is that you no longer have to install the application and its dependencies manually on the machine, but can start a container instead. The container is based on a so-called Docker image, which already contains the installed application.

Profiles started via bwJupyter are started as containers. Therefore, you can use your own Docker images to customize the Jupyter environment.

You can use Docker via Docker Desktop. The installation instructions depend on the operating system you are using. The specific steps and instructions can be found in the Docker documentation.

Note: Since this is virtualization software, the installation is somewhat more complex and time-consuming compared to conventional software.

 

Create Dockerfile

Once Docker has been successfully installed, you can create the Dockerfile. The Dockerfile is a file named Dockerfile without a file extension. This file contains all the instructions for an executable JupyterLab environment. To avoid having to install the JupyterLab software yourself within your Dockerfiles, you can build on a so-called base image. You can find a list of possible base images in the Jupyter documentation.

Note: If available, specify the current JupyterHub version 5.2.1 in the tag of the base image.

In the following, we use the Datascience image and additionally install the Python package cowsay. To do this, we create the file Dockerfile (without file extension) and insert the following content.

FROM quay.io/jupyter/datascience-notebook:hub-5.2.1
RUN pip install cowsay==6.1

If you want to install more complex packages that require system dependencies, you can also execute commands as a root user in the Dockerfile. It is important that you switch back to the jovyan user at the end. The following Dockerfile installs the process manager htop.

FROM quay.io/jupyter/datascience-notebook:hub-5.2.1
USER root

# Install htop
RUN apt-get update --yes && \
    apt-get install --yes --no-install-recommends \
    htop \
    apt-get clean && rm -rf /var/lib/apt/lists/*

USER jovyan

Further information on Dockerfiles can be found in the Docker documentation.

Notes:

  • The folder/home/jovyan/work will be overwritten with the user's personal directory after the container is started. If you want to share files with students, use the shared folder __shared.
  • Please do not upload large files to the Dockerfile. Instead, use the shared folder within the profile.
  • If you provide your own Docker images, you are responsible for ensuring that you do not install any malicious packages or software. Make sure that the packages come from a secure source and that you trust the source.

 

Build Docker image

Once you have created the Dockerfile, you can build it into a Docker image. To do this, simply execute the docker build command in the Dockerfile directory. . 

docker build -t bwjupyter-profile


Select container registry and provide Docker image

In the final step, you must deploy the Docker image so that bwJupyter can download and use it. To do this, you must first select a container registry to deploy your image. The most common container registries are listed below.

Container registry Introduction Comments
Docker Hub Build and push an image to Docker Hub DockerHub allows a free private Docker image.
GHCR (GitHub Container Registry) Working with the Container registry Instead of a password, a Token (scope "write:packages") should be used to pull a private Docker image.
quay.io Getting Started with Quay.io Quay.io does not allow free private Docker images.
GitLab CR (GitLab Container Registry) Build and push container images to the container registry  

After selecting a container registry, you must log in using the docker login command. You must then rename (tag) your built image so that it is included in the container registry (docker tag). Finally, you can upload (push) the renamed image using the docker push command.

Additional notes:

  • Find out whether your institution already operates its own container registry that you can use.
  • Currently, Docker images must be publicly available without registration. We are already working on a solution that will allow the use of private Docker images.