Self-host

This walkthrough gets a routess instance running on your own machine or server in about five minutes. For Kubernetes, see Kubernetes.

What you needCopy Anchor Link

• Docker and Docker Compose v2 (modern Docker Desktop or Docker Engine ships with both).
• A Google OAuth client for Google sign-in (the compose file requires it). Users can also sign in with email + password once the stack is up.
• A Mapbox access token; the free tier is fine.
• A Valhalla routing engine (VALHALLA_URL). Route calculation and surface analysis go through it; without it the routing endpoints return 503.
• Long random strings for JWT_SECRET, ANALYTICS_SALT, PAT_PEPPER, and DB_PASSWORD. Generate with openssl rand -base64 32.

Optional, gracefully disabled when unset:

• Resend for transactional email (without it, verification URLs are logged to stdout).
• Sentry / GlitchTip for browser error reporting.
• Umami for product analytics.
• Admin role for accessing the in-app admin panel.

Set up Google OAuthCopy Anchor Link

1. Open the Google Cloud Console credentials page.
2. Create an OAuth 2.0 Client ID of type Web application.
3. Under Authorized JavaScript origins, add the URL your users will open (e.g. http://localhost:8080 or https://routess.example.com).
4. Under Authorized redirect URIs, add <your-web-url>/auth/callback.
5. Copy the Client ID and Client secret.

Get a Mapbox tokenCopy Anchor Link

1. Sign up at account.mapbox.com.
2. Create a public access token (pk.…) under Access tokens.
3. Restrict it to your domain when you go to production.

Run itCopy Anchor Link

git clone https://github.com/robbeverhelst/routess.git
cd routess
cp docker/.env.selfhost.example .env
# edit .env and fill in the required values
docker compose -f docker/compose.selfhost.yaml --project-directory . up -d

Then open http://localhost:8080.

The stack starts four containers:

Change the host ports via WEB_PORT, API_PORT, DOCS_PORT in .env.

Pin a versionCopy Anchor Link

Default tag is latest. For production, pin to a specific release:

ROUTESS_TAG=1.122.7 docker compose -f docker/compose.selfhost.yaml --project-directory . up -d

Or set ROUTESS_TAG in .env. See the releases page for available tags.

Environment variablesCopy Anchor Link

The .env file in docker/.env.selfhost.example is the source of truth. The variables you'll touch most often:

Advanced variablesCopy Anchor Link

The API understands more knobs than the compose file passes through. To use one, add it under the api service environment in docker/compose.selfhost.yaml (or your own override file):

For the web container:

Browser console logging defaults to warn. To debug a single browser, set localStorage["routess:log-level"] to debug, info, warn, error, or none and reload.

Billing (hosted product only)Copy Anchor Link

Routess.com sells a Pro year pass (ADR 0039). A self-hosted instance leaves billing off, which is the default: every feature stays unlocked, everyone gets GENERATION_QUOTA_PER_DAY route generations a day, and no payment provider is contacted. Keep BILLING_ENABLED=false, or leave it unset.

For reference, these are the variables the hosted product sets. With BILLING_ENABLED=true the API refuses to start unless the launch moment and all three Stripe values are set.

Put it behind a reverse proxyCopy Anchor Link

The default compose exposes ports directly. For TLS and a real domain, front the web and api services with a reverse proxy (Caddy, Traefik, ingress-nginx, Cloudflare Tunnel) and override the public URLs in .env:

PUBLIC_WEB_URL=https://routess.example.com
PUBLIC_API_URL=https://api.routess.example.com

PUBLIC_WEB_URL is also used as the OAuth redirect base, so it must match what you configured in Google Cloud.

UpgradeCopy Anchor Link

Take a database backup first (see below); migrations are forward-only, so a snapshot is your rollback path. Then:

docker compose -f docker/compose.selfhost.yaml --project-directory . pull
docker compose -f docker/compose.selfhost.yaml --project-directory . up -d

The API runs migrations automatically on startup. There is no manual migration step. To roll back, restore the pre-upgrade dump and pin ROUTESS_TAG to the previous release.

Back upCopy Anchor Link

The Postgres data lives in the postgres_data named volume. Standard pg_dump works:

docker compose -f docker/compose.selfhost.yaml --project-directory . exec postgres \
  pg_dump -U routess routess > routess-$(date +%F).sql

Restore into a fresh volume with psql:

docker compose -f docker/compose.selfhost.yaml --project-directory . exec -T postgres \
  psql -U routess routess < routess-2026-06-04.sql

TroubleshootingCopy Anchor Link

• Is the API healthy? curl http://localhost:3000/health/ready returns 200 when the API can reach the database; /health/live checks only that the process is up.
• "address already in use" on :8080 or :3000: change WEB_PORT / API_PORT in .env.
• Google sign-in returns redirect_uri_mismatch: the OAuth client's authorised redirect URI must exactly match <PUBLIC_WEB_URL>/auth/callback.
• Map tiles don't load: verify VITE_MAPBOX_ACCESS_TOKEN is set; check browser devtools for 401s from api.mapbox.com.
• Verification emails not arriving: set RESEND_API_KEY and EMAIL_FROM. Without them the API logs the verification URL to stdout; run docker compose logs api | grep '\[email:console\]'.