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.
• r_env (R): A full R environment for statistical computing and visualization (available in specific container variants).

---

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

Now is a good time to open the .env file and set your JUPYTER_PASSWORD. If you skip this, a random token will be generated.

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 or the token from the logs (default password: eX4mP13p455w0Rd). By default, the ~/notebooks directory on your host machine is mapped into the container, so you can easily access your files.

If you did not provide a password in .env, get the token from the Docker logs to login:

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. Contains new test features but may be unstable.

Language & Tool Flavors:

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

• :r_latest / :r_vX.Y.Z: Extends the base image with a full R environment.
• Mapnik, GRASS, QGIS: Due to resource constraints, these massive images are not pushed to our public registry automatically. We provide simple docker-compose.<flavor>.yml files so you can easily build them locally on your host machine. Refer to our 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

---

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.