Multi-Container JupyterHub

This is an example deployment of a multi-container JupyterHub. This JupyterHub uses an extended version of the DockerSpawner to spawn single-user containers with access to one GPU, provided one is available. These instructions apply to Windows.

Prerequisites

To set up this JupyterHub, you will need to have installed:

• Docker Desktop for Windows
• Ubuntu for WSL2
• NVIDIA Container Toolkit on Ubuntu for WSL2

Configure Docker Desktop

Prior to building the Dockerfile, Docker must be allowed to access the GPUs. To do this:

1. Navigate to the settings page for Docker Desktop and go to "Resources" > "WSL Integration";
2. Check the option "Enable integration with my default WSL distro";
3. Toggle on the integration with Ubuntu; and
4. Click "Apply & restart".

You can check that the Docker Engine has access by running,

docker run --rm --gpus all ubuntu nvidia-smi

The output should be a table.

The JupyterHub also relies on a network. To create it, run:

docker network create jupyternet

Configuration

Depending on your situation, you may wish to make some changes. Some of the configuration settings can be changed in jupyterhub_config.py, much of the documentation is here.

Changing the Authenticator

Currently, the authenticator is a dummy authenticator used for testing. This is specified in jupyterhub_config.py. If you don't specify an authenticator, then the default PAM-based Authenticator is used. You can also change the authenticator by writing a new one or using an existing service.

Setting the Root Password

WIP

Number of GPUs

If your system has more than one GPU, go to the .env file and modify it accordingly:

• If you have two GPUs, type "01";
• If you have three GPUs, type "012";
• and so on and so forth.

Modify the GPUDockerSpawner

The GPUDockerSpawner has several attributes that you can change. All the attributes of the DockerSpawner are fully contained in the GPUDockerSpawner. The documentation is here. The GPUDockerSpawner has one additional attribute: gpu_notebooks. This attribute is a list containing all the GPU-accelerated notebooks from which the user can choose to spawn.

If you want to modify the behavior of the GPUDockerSpawner, take the wheel file and change the file extension to ".zip". Navigate to "gpudockerspawner" > "gpudockerspawner.py" to make your changes. Once you are complete, create the wheel file from the Python project (instructions) and update the Dockerfile.

Enabling HTTPS

WIP

Starting the JupyterHub

Once you have finished modifying the files to your liking, run:

docker compose up

Congratulations! You've created your own JupyterHub.