Docker Container Setup¶

Carto-Lab Docker is a project that provides a complete, versioned instance of JupyterLab inside a Docker container. It is designed to be a FAIR-enabling environment for spatial data science.

The container comes with two pre-configured, curated environments:

• worker_env (Python): Contains the most important packages for open-source cartography and spatial analysis (available in the base image/all flavors).
• r_env (R): A full R environment for statistical computing and visualization (available in the r flavor).

Step by Step: Running the Container¶

This guide provides the fastest way to get a local instance running.

Prerequisites: Docker and Git must be installed.

1. Clone the Repository¶

git clone https://github.com/ioer-dresden/carto-lab-docker
cd carto-lab-docker

2. Create Your Configuration¶

Copy the example .env file. This file stores your local settings.

cp .env.example .env

Open the .env file and customize your settings (e.g. JUPYTER_PASSWORD, persistent paths, and Git user credentials).

3. Create the Docker Network¶

This one-time command creates a network that allows Carto-Lab Docker to communicate with other services like databases (e.g. hlldb or rawdb).

docker network create lbsn-network

4. Pull and Run¶

This command pulls the latest stable image from our registry and starts the container in the background.

docker compose pull && docker compose up -d

5. Access JupyterLab¶

Open your browser and navigate to http://localhost:8888. Log in with the password you set in .env (default fallback password: eX4mP13p455w0Rd).

• Persistent Notebooks: By default, ~/notebooks on your host machine is mapped to /home/jovyan/work inside the container.
• Persistent Settings & Sessions: UI themes, open workspace tabs, and session cookies are preserved in ~/.cartolab_state on your host.

If you enabled GENERATE_TOKEN=true in .env, retrieve the login token from the Docker logs:

docker compose logs | grep "?token=" | tail -n 2

Configuration & Container Versions¶

You can customize your Carto-Lab Docker instance by editing the .env file.

Choosing a Container Version (Tag)¶

We provide several container variants for different needs via our container registries (Quay.io and GitLab).

Core Base Images:

• :latest: The current stable, production-ready image.
• :vX.Y.Z (e.g., :v1.1.0): Immutable, specific release versions. Strongly recommended for scientific reproducibility.
• :dev: The bleeding-edge image built on every commit to master-latest. Contains new test features but may be unstable.

Language & Tool Flavors:

Because geospatial engines can be quite large, we provide specialized extensions (flavors):

• :r_latest / :r_dev / :r_vX.Y.Z: Extends the base image with a full R environment.
• Mapnik, GRASS, QGIS: Due to resource constraints, these images are not pushed to our public registry automatically. We provide simple overlay docker-compose.<flavor>.yml files so you can easily build and run them locally. See below or refer to our full developer documentation on how to build these flavors.

To use a different variant or version, edit the TAG variable in your .env file:

# In your .env file
# Use a specific, reproducible base image
TAG=v1.1.0

Or, use the bleeding-edge dev version for testing:

TAG=dev
# TAG=r_dev

The tag dev stands for the baseline image (only Python), r_dev for the R flavor (Python+R). Note: We do not publish dev-images for the other flavors.

COMPOSE_FILE=docker-compose.yml:docker-compose.qgis.yml

docker compose build && docker compose up -d

COMPOSE_FILE=docker-compose.yml:docker-compose.qgis.yml:docker-compose.override.yml

For Developers and Administrators¶

For advanced topics such as building images locally, setting up a public-facing instance with a reverse proxy, or understanding the security model, please refer to our Developer Guide. This guide includes critical information on our "root in the container, rootless on the host" security philosophy.