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 Go sidecar handles 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. (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. For a truly offline deployment, download a basemap once and point Caddy at it:

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                          # pick up the new TILES_URL

City and country regions can be built smaller with Planetiler — see the README for the one-liner.

Where to next​