QGIS & JupyterGIS Integration¶

Carto-Lab Docker supports QGIS through a :qgis flavor. This image extends the base container by injecting the QGIS desktop engine and the jupytergis-qgis bridge.

This allows you to: 1. Open native .qgz files directly in the JupyterLab browser UI via JupyterGIS. 2. Programmatically execute QGIS geoprocessing algorithms inside your Jupyter Notebooks using import qgis.core.

Usage¶

Use the following docker-compose.qgis.yml:

services:
  jupyterlab:
    image: quay.io/ioer-fdz/carto-lab-docker:qgis
    # image: gcr.hrz.tu-chemnitz.de/ioer/fdz/carto-lab-docker:grass
    build:
      context: ./qgis
      args:
        - VERSION=${TAG:-latest}
    restart: "no"
    ports:
      - 127.0.0.1:${JUPYTER_WEBPORT:-8888}:8888
    volumes:
      - ${JUPYTER_NOTEBOOKS:-~/notebooks}:/home/jovyan/work
      - ${CONDA_ENVS:-~/envs}:/envs
    environment:
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-eX4mP13p455w0Rd}
      - JUPYTER_PASSWORD=${JUPYTER_PASSWORD:-eX4mP13p455w0Rd}
      - JUPYTER_WEBURL=${JUPYTER_WEBURL:-http://localhost:8888}
      - JUPYTER_EXTRA_ARGS=${JUPYTER_EXTRA_ARGS:-}
    env_file: ".env"
    networks:
      - lbsn-network

networks:
  lbsn-network:
    name: ${NETWORK_NAME:-lbsn-network}
    external: true

See the qgis/Dockerfile file for the list of Grass dependencies:

ARG VERSION=latest

## public:
# FROM quay.io/ioer-fdz/carto-lab-docker:$VERSION
## private:
FROM gcr.hrz.tu-chemnitz.de/ioer/fdz/carto-lab-docker:$VERSION

# 1. Install QGIS and the jupytergis-qgis bridge into the Server Environment.
# Use `conda install` (not mamba) so it respects CONDA_SOLVER=rattler.
RUN CONDA_REPODATA_THREADS=1 CONDA_SOLVER=rattler CONDA_METADATA_STRATEGY=none \
    conda install -n jupyter_env qgis jupytergis-qgis --channel conda-forge --yes \
    && mamba clean --all --force-pkgs-dirs --yes

# 2. Recreate the Worker Environment from scratch with QGIS included
RUN sed -i 's/- python>=3.10,<3.13/- python>=3.10/g' /environment_default.yml \
    && sed -i '/- pyarrow/d' /environment_default.yml \
    && echo "  - qgis" >> /environment_default.yml \
    && echo "  - jupytergis" >> /environment_default.yml \
    && echo "  - jupytergis-qgis" >> /environment_default.yml \
    && echo "  - ipykernel" >> /environment_default.yml \
    # Explicitly remove the old environment to allow a clean creation
    && rm -rf /opt/conda/envs/worker_env \
    # Create the new environment
    && CONDA_REPODATA_THREADS=1 CONDA_SOLVER=rattler CONDA_METADATA_STRATEGY=none \
    conda env create -n worker_env --file /environment_default.yml \
    # Re-register the Jupyter Kernel since the environment was wiped
    && source /opt/conda/bin/activate worker_env \
    && ipython kernel install --user --name=worker_env \
    && sed -i '/"display_name": "worker_env",/a "env":{"PROJ_LIB": "/opt/conda/envs/worker_env/share/proj"},' \
    /root/.local/share/jupyter/kernels/worker_env/kernel.json \
    && mamba clean --all --force-pkgs-dirs --yes

Building the Image¶

If you want to build a specific version locally against the newest base image:

docker compose -f docker-compose.qgis.yml build \
        --no-cache --progress=plain \
    && docker compose -f docker-compose.qgis.yml up -d

See the developer section for more information.