README.md

See the CUDA-enabled JupyterLab QGIS docker stack for GPU accelerated docker images.

JupyterLab QGIS docker stack

Multi-arch (linux/amd64, linux/arm64/v8) docker images:

• glcr.b-data.ch/jupyterlab/qgis/base

Images considered stable for QGIS versions ≥ 3.28.3 and ≥ 3.22.16 (LTR).

Features

• JupyterLab: A web-based interactive development environment for Jupyter notebooks, code, and data. The images include
  • Git: A distributed version-control system for tracking changes in source code.
  • Python: An interpreted, object-oriented, high-level programming language with dynamic semantics.
  • TurboVNC: A high-speed version of VNC derived from TightVNC.
    ℹ️ Tuned to maximize performance for image-intensive applications.
  • Zsh: A shell designed for interactive use, although it is also a powerful scripting language.
  • Xfce (via noVNC + TurboVNC): A lightweight desktop environment for UNIX-like operating systems.
    • GRASS GIS: A free and open source Geographic Information System (GIS).
    • Orfeo Toolbox: An open-source project for state-of-the-art remote sensing.
      ℹ️ amd64 only
    • QGIS: A free, open source, cross platform (lin/win/mac) geographical information system (GIS).
    • SAGA GIS: A Geographic Information System (GIS) software with immense capabilities for geodata processing and analysis.

👉 See the Version Matrix for detailed information.

Subtags

• {QGIS_VERSION,latest,ltr}-root: Container runs as root

Table of Contents

• Prerequisites
• Install
• Usage
• Similar projects
• Contributing
• Support
• Sponsors
• License

Prerequisites

This projects requires an installation of docker.

Install

To install docker, follow the instructions for your platform:

• Install Docker Engine | Docker Documentation > Supported platforms
• Post-installation steps for Linux

Usage

Build image (base)

latest:

cd base && docker build \
  --build-arg QGIS_VERSION=3.38.4 \
  --build-arg SAGA_VERSION=9.1.3 \
  --build-arg OTB_VERSION=9.1.0 \
  --build-arg PROC_SAGA_NG_VERSION=1.0.0 \
  --build-arg PYTHON_VERSION=3.12.7 \
  --build-arg GIT_VERSION=2.47.0 \
  -t jupyterlab/qgis/base \
  -f Dockerfile .

ltr:

cd base && docker build \
  --build-arg QGIS_VERSION=3.34.12 \
  --build-arg SAGA_VERSION=9.1.3 \
  --build-arg OTB_VERSION=8.1.2 \
  --build-arg PROC_SAGA_NG_VERSION=1.0.0 \
  --build-arg PYTHON_VERSION=3.11.10 \
  --build-arg GIT_VERSION=2.47.0 \
  -t jupyterlab/qgis/base:ltr \
  -f Dockerfile .

version:

cd base && docker build \
  -t jupyterlab/qgis/base:MAJOR.MINOR.PATCH \
  -f MAJOR.MINOR.PATCH.Dockerfile .

For MAJOR.MINOR.PATCH ≥ 3.28.3 and MAJOR.MINOR.PATCH ≥ 3.22.16 (LTR versions).

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 \
  -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/qgis/base{:ltr,:MAJOR[.MINOR[.PATCH]]}

from the project's GitLab Container Registries:

docker run -it --rm \
  -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

• glcr.b-data.ch/jupyterlab/qgis/base

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+, 3.28.12+ (LTR))

Create an empty home directory:

mkdir "${PWD}/jupyterlab-root"

Use the following command to run the container as root:

podman run -it --rm \
  -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 \
  -p 8888:8888 \
  -v "${PWD}/jupyterlab-jovyan":/home/jovyan \
  IMAGE{:ltr,:MAJOR[.MINOR[.PATCH]]}

might be sufficient.

Similar projects

• pangeo-data/jupyter-earth
• geocompx/docker

What makes this project different:

1. Multi-arch: linux/amd64, linux/arm64/v8
   ℹ️ Runs on Apple M series using Docker Desktop.
2. Base image: Debian instead of Ubuntu
   ℹ️ CUDA-enabled images are Ubuntu-based.
3. TurboVNC: High-speed VNC version
4. Just Python – no Conda / Mamba

See Notes for tweaks, settings, etc.

Contributing

PRs accepted.

This project follows the Contributor Covenant Code of Conduct.

Support

Community support: Open a new discussion here. Commercial support: Contact b-data by email.

b-data tailors the JupyterLab images to your needs, e.g.

• Integration of self-signed CA certificates to enable communication with web services on the intranet.
• Setting up the necessary environment variables so that everything works behind a corporate proxy server.

Additionally, the JupyterHub setup can be customised to allow

• authentication with AD/LDAP
• mounting CIFS/SMB file shares

and much more.

Sponsors

Work partially funded by

License

Copyright © 2023 b-data GmbH

Distributed under the terms of the MIT License, with exceptions.