Skip to main content

Quickstart

Start the Atlas app, then use the setup wizard to choose the data you need. Downloading and preparing datasets can take minutes or hours; the first map screen does not mean that search or routing data is ready.

1. Prepare the checkout​

You need Docker with Compose v2 and enough disk space for your selected datasets. Allow space for both downloads and prepared indexes. A small routing extract does not reduce the separately configured Photon search index.

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

Compose defaults work without an .env. To override them, copy .env.example to .env and edit the values you need. For a release-pinned app image, set:

APP_IMAGE=ghcr.io/dawarich-app/atlas/app:0.6.0

The app uses SQLite by default and generates a signing secret on first boot, stored under data/app/. Preserve that directory across container recreation. DATABASE_URL is not required for the default installation. Set PUID and PGID when the host data directories need a particular owner.

2. Start Atlas​

docker compose up -d

Open http://localhost:8484. A fresh installation opens setup; an existing one opens the map. You can reopen the wizard from Settings → Setup wizard.

The standard deployment gives Atlas access to the host Docker socket so it can prepare regions and manage services. Keep access to the map and setup interface restricted to trusted users. ADMIN_USERNAME and ADMIN_PASSWORD protect the separate /admin routes; they do not add authentication to the main map, setup wizard or Transport data page.

3. Choose features and data​

Follow the setup wizard:

  1. Choose address search, street routes, public transport and/or places.
  2. Select a region such as Berlin (city). Source sizes are estimates of regional PBF downloads, not total disk usage.
  3. For transit, connect a timetable in Transport data and choose one of MOTIS or OpenTripPlanner. Missing coverage produces a warning; other features can still be installed.
  4. Review and start installation. Follow progress while using ready features.

Photon uses the deployment's COUNTRY_CODE index independently of the selected street region. Placeholder downloads its prebuilt database when enabled; manual WhosOnFirst preparation is not required for normal search setup.

Use Settings → Services → Regions and data to inspect each service's inputs. Search, road routing and transit may cover different areas. Compose profiles explains manual service management; use Atlas's exclusive selector to switch transit engines.

4. Verify search and routing​

Search for Brandenburger Tor, Berlin when the German Photon index is ready. Use Route here or Start here on the selected place to try Directions. Try Alexanderplatz as the other endpoint if your routing dataset covers Berlin.

From a terminal:

curl 'http://localhost:8484/api/v1/version'
curl 'http://localhost:8484/api/v1/search?q=alexanderplatz&limit=3'
docker compose ps
docker compose logs -f photon valhalla

For unavailable services, the map's recovery action opens Settings → Services. Check preparation errors and coverage there. Service status is derived from logs and can lag actual API readiness.

5. Choose a basemap​

Open Settings → Basemap to see the current source, select an online style or configure a downloaded map. Online maps require network access. Downloading a planet-wide map needs substantial disk space; review the displayed estimate before starting. Regional search and routing datasets are separate from basemap storage.

Next steps​