Skip to content

Latest commit

 

History

History
221 lines (164 loc) · 6.15 KB

CUDA.md

File metadata and controls

221 lines (164 loc) · 6.15 KB
Raw

CUDA-enabled JupyterLab QGIS docker stack

GPU accelerated, multi-arch (linux/amd64, linux/arm64/v8) docker images:

Images available for QGIS versions ≥ 3.34.0.

CUDA screenshot

Features

The same as the JupyterLab QGIS docker stack plus

  • VirtualGL: Enables OpenGL applications to run with full GPU acceleration.
  • CUDA runtime, CUDA math libraries and NCCL

👉 See the CUDA Version Matrix for detailed information.

Subtags

The same as the JupyterLab QGIS docker stack.

Table of Contents

Prerequisites

The same as the JupyterLab QGIS docker stack plus

  • NVIDIA GPU
  • NVIDIA Linux driver
  • NVIDIA Container Toolkit

ℹ️ The host running the GPU accelerated images only requires the NVIDIA driver, the CUDA toolkit does not have to be installed.

Use driver version 535 (Long Term Support Branch) with NVIDIA Data Center GPUs or select NGC-Ready NVIDIA RTX boards to ensure forward compatibility until June 2026.

Install

To install the NVIDIA Container Toolkit, follow the instructions for your platform:

Usage

Build image (base)

latest:

cd base && docker build \
  --build-arg BASE_IMAGE=ubuntu \
  --build-arg BASE_IMAGE_TAG=22.04 \
  --build-arg CUDA_IMAGE=nvidia/cuda \
  --build-arg CUDA_IMAGE_SUBTAG=runtime-ubuntu22.04 \
  --build-arg CUDA_VERSION=12.6.2 \
  --build-arg QGIS_VERSION=3.38.4 \
  --build-arg OTB_VERSION=9.1.0 \
  --build-arg PYTHON_VERSION=3.12.7 \
  --build-arg GIT_VERSION=2.47.0 \
  -t jupyterlab/cuda/qgis/base \
  -f Dockerfile .

ltr/version:

cd base && docker build \
  --build-arg BASE_IMAGE=ubuntu \
  --build-arg BASE_IMAGE_TAG=22.04 \
  --build-arg CUDA_IMAGE=nvidia/cuda \
  --build-arg CUDA_IMAGE_SUBTAG=runtime-ubuntu22.04 \
  --build-arg CUDA_VERSION=11.8.0 \
  --build-arg QGIS_VERSION=3.34.12 \
  --build-arg OTB_VERSION=8.1.2 \
  --build-arg PYTHON_VERSION=3.11.10 \
  --build-arg GIT_VERSION=2.47.0 \
  -t jupyterlab/cuda/qgis/base:ltr \
  -f Dockerfile .

Create home directory

Create an empty directory using docker:

docker run --rm \
  -v "${PWD}/jupyterlab-jovyan":/dummy \
  alpine chown 1000:100 /dummy

It will be bind mounted as the JupyterLab user's home directory and automatically populated.
❗ Bind mounting a subfolder of the home directory is only possible for images with QGIS version ≥ 3.34.4.

Run container

self built:

docker run -it --rm \
  --gpus 'device=all' \
  -p 8888:8888 \
  -u root \
  -v "${PWD}/jupyterlab-jovyan":/home/jovyan \
  -e NB_UID=$(id -u) \
  -e NB_GID=$(id -g) \
  -e CHOWN_HOME=yes \
  -e CHOWN_HOME_OPTS='-R' \
  jupyterlab/cuda/qgis/base{:ltr,:MAJOR.MINOR.PATCH}

from the project's GitLab Container Registries:

docker run -it --rm \
  --gpus 'device=all' \
  -p 8888:8888 \
  -u root \
  -v "${PWD}/jupyterlab-jovyan":/home/jovyan \
  -e NB_UID=$(id -u) \
  -e NB_GID=$(id -g) \
  -e CHOWN_HOME=yes \
  -e CHOWN_HOME_OPTS='-R' \
  IMAGE{:ltr,:MAJOR[.MINOR[.PATCH]]}

IMAGE being one of

The use of the -v flag in the command mounts the empty directory on the host (${PWD}/jupyterlab-jovyan in the command) as /home/jovyan in the container.

-e NB_UID=$(id -u) -e NB_GID=$(id -g) instructs the startup script to switch the user ID and the primary group ID of ${NB_USER} to the user and group ID of the one executing the command.

-e CHOWN_HOME=yes -e CHOWN_HOME_OPTS='-R' instructs the startup script to recursively change the ${NB_USER} home directory owner and group to the current value of ${NB_UID} and ${NB_GID}.
ℹ️ This is only required for the first run.

The server logs appear in the terminal.

Using Podman (rootless mode, 3.34.0+)

Create an empty home directory:

mkdir "${PWD}/jupyterlab-root"

Use the following command to run the container as root:

podman run -it --rm \
  --device 'nvidia.com/gpu=all' \
  -p 8888:8888 \
  -u root \
  -v "${PWD}/jupyterlab-root":/home/root \
  -e NB_USER=root \
  -e NB_UID=0 \
  -e NB_GID=0 \
  -e NOTEBOOK_ARGS="--allow-root" \
  IMAGE{:ltr,:MAJOR[.MINOR[.PATCH]]}

#### Using Docker Desktop

Creating a home directory might not be required. Also

docker run -it --rm \
  --gpus 'device=all' \
  -p 8888:8888 \
  -v "${PWD}/jupyterlab-jovyan":/home/jovyan \
  IMAGE{:ltr,:MAJOR[.MINOR[.PATCH]]}

might be sufficient.

Similar projects

None. I would like to mention

which also relies on VirtualGL (EGL backend) for direct access to the GPU.

What makes this project unique:

  1. Multi-arch: linux/amd64, linux/arm64/v8
    ℹ️ No GPU acceleration on Apple M series.
  2. Derived from nvidia/cuda:12.6.2-runtime-ubuntu22.04
  3. VirtualGL: Fully GPU accelerated OpenGL applications
  4. Just Python – no Conda / Mamba

See Notes for tweaks, settings, etc.