Skip to main content

Quickstart

From a clean clone to a working map in under five minutes (city scale). The whole flow is plain docker compose — no Makefile, no custom CLI.

Prerequisites​

  • Docker + Docker Compose v2
  • 10 GB free disk for a single city, ~73 GB for Germany, ~1.15 TB for the planet
  • curl and jq if you want to poke the API from a terminal

1. Clone and pick a region​

git clone https://github.com/dawarich-app/atlas.git
cd atlas

cp regions/berlin.env .env          # city — ~30 MB PBF, smallest viable footprint
# or:
cp regions/germany.env .env         # country — ~4 GB PBF
cp regions/europe.env .env          # continent — ~30 GB PBF
cp regions/planet.env .env          # full Earth — ~75 GB PBF
ls regions/                         # see all built-in presets

Each regions/<name>.env is a complete env file: PBF URL, Photon country code, default map view, PMTiles URL. Copying it into .env is enough for Docker Compose to pick it up.

A fresh .env has no SECRET_KEY_BASE set. Atlas generates a development one on first boot. For production runs, append your own SECRET_KEY_BASE=… and DATABASE_URL=… to .env after the copy.

2. Boot the bare stack​

docker compose up -d

This starts only caddy and Dawarich Atlas — every other service is gated behind a Compose profile. Visit http://localhost:8484 — the map loads immediately. Search, routing and POIs return graceful upstream: unavailable until you bring those services up.

3. Add data layers​

The four data profiles are independent — you can run them in any order, or in parallel. Each service downloads + indexes its dataset on first boot.

docker compose --profile geocoding up -d    # Photon + Placeholder + libpostal (~10 min ready)
docker compose --profile routing   up -d    # Valhalla — drive/cycle/walk + elevation (30–50 min on Germany)
docker compose --profile pois      up -d    # Overpass — POIs in radius (hours on Germany)
docker compose --profile transit   up -d    # OpenTripPlanner — needs GTFS in data/gtfs/

Or boot everything (except transit) in one shot:

COMPOSE_PROFILES=all docker compose up -d

You can also flip these on/off from the Atlas admin panel — open localhost:8484, click the Settings tab, toggle services, hit Save & apply. The app's in-app control plane runs the actual docker compose calls behind the scenes.

Placeholder needs a one-shot data-prep run before it can boot. Either let --profile geocoding pull it on first start, or pre-seed with docker compose --profile data-setup run --rm whosonfirst. See Compose profiles for the underlying mechanics.

4. Verify​

docker compose ps                                       # container state per service
docker compose logs -f photon valhalla overpass         # follow ingest progress
du -sh data/*                                           # per-service disk footprint

A first happy-path API call:

curl 'http://localhost:8484/api/v1/search?q=alexanderplatz&limit=3' | jq .

5. Enable the admin panel​

The map page lazy-loads an admin panel (cog icon → Settings tab) for toggling services and switching regions. Auth is HTTP Basic, controlled via env vars:

echo 'ADMIN_USERNAME=admin' >> .env
echo 'ADMIN_PASSWORD=use-a-real-password' >> .env
docker compose up -d

Once enabled, the panel lets you:

  • Toggle Search / Routing / POIs / Transit on or off (with disk + ETA preview before downloads)
  • Pick a region (Berlin, Germany, Europe, planet, multi-region presets)
  • Configure the basemap (remote URL or local file)
  • Watch progress stream live over the LiveView WebSocket as data services boot and ingest

Every action runs through the app's in-app control plane, which drives the host Docker socket directly (mounted into the container, guarded by DOCKER_GID). OpenAPI for the public API is served by the app at http://localhost:8484/api/v1/openapi.json; the admin control-plane reference lives on the Admin API page.

6. (Optional) Offline base map​

By default the map streams Protomaps PMTiles from a remote URL via HTTP range requests — 0 GB on disk, instant boot. Daily Protomaps builds live at https://build.protomaps.com/<YYYYMMDD>.pmtiles (~105 GB planet-wide). Point Atlas at one:

echo 'TILES_URL=https://build.protomaps.com/20260514.pmtiles' >> .env
docker compose up -d caddy app

For a fully offline deployment, download the file once and let Caddy serve it locally:

mkdir -p data/tiles
curl -L "https://build.protomaps.com/$(date +%Y%m%d).pmtiles" \
  -o data/tiles/basemap.pmtiles

echo 'TILES_URL=/tiles/basemap.pmtiles' >> .env
docker compose up -d caddy app

Five built-in themes via protomaps-themes-base: light (default), dark, grayscale, white, black. Switch via TILES_THEME in .env.

Where to next​