Self-host

Deze handleiding krijgt een routess-instantie op je eigen machine of server draaiend in ongeveer vijf minuten. Voor Kubernetes, zie Kubernetes.

Wat je nodig hebtCopy Anchor Link

• Docker en Docker Compose v2 (een moderne Docker Desktop of Docker Engine komt met allebei).
• Een Google OAuth-client voor Google-aanmelding (het compose-bestand vereist het). Gebruikers kunnen ook met e-mail + wachtwoord aanmelden zodra de stack draait.
• Een Mapbox access token; de gratis tier volstaat.
• Een Valhalla-routing-engine (VALHALLA_URL). Routeberekening en wegdekanalyse lopen erlangs; zonder geven de routing-endpoints 503 terug.
• Lange willekeurige strings voor JWT_SECRET, ANALYTICS_SALT, PAT_PEPPER en DB_PASSWORD. Genereer ze met openssl rand -base64 32.

Optioneel, netjes uitgeschakeld wanneer niet gezet:

• Resend voor transactionele e-mail (zonder dit worden verificatie-URL's naar stdout gelogd).
• Sentry / GlitchTip voor het rapporteren van browserfouten.
• Umami voor productanalytics.
• Adminrol voor toegang tot het ingebouwde adminpaneel.

Google OAuth instellenCopy Anchor Link

1. Open de credentials-pagina van de Google Cloud Console.
2. Maak een OAuth 2.0 Client ID van het type Web application.
3. Voeg onder Authorized JavaScript origins de URL toe die je gebruikers openen (bv. http://localhost:8080 of https://routess.example.com).
4. Voeg onder Authorized redirect URIs <your-web-url>/auth/callback toe.
5. Kopieer de Client ID en het Client secret.

Een Mapbox-token ophalenCopy Anchor Link

1. Meld je aan op account.mapbox.com.
2. Maak een public access token (pk.…) onder Access tokens.
3. Beperk het tot je domein wanneer je naar productie gaat.

DraaienCopy 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

Open daarna http://localhost:8080.

De stack start vier containers:

Wijzig de host-poorten via WEB_PORT, API_PORT, DOCS_PORT in .env.

Een versie pinnenCopy Anchor Link

De standaardtag is latest. Pin voor productie naar een specifieke release:

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

Of zet ROUTESS_TAG in .env. Zie de releases-pagina voor de beschikbare tags.

OmgevingsvariabelenCopy Anchor Link

Het .env-bestand in docker/.env.selfhost.example is de bron van waarheid. De variabelen die je het vaakst aanraakt:

Geavanceerde variabelenCopy Anchor Link

De API begrijpt meer knoppen dan het compose-bestand doorgeeft. Om er een te gebruiken, voeg je hem toe onder de environment van de api-service in docker/compose.selfhost.yaml (of je eigen override-bestand):

Voor de web-container:

Console-logging in de browser staat standaard op warn. Om één browser te debuggen, zet je localStorage["routess:log-level"] op debug, info, warn, error of none en herlaad je.

Betalingen (alleen het gehoste product)Copy Anchor Link

Routess.com verkoopt een Pro-jaarpas (ADR 0039). Een zelf gehoste installatie laat betalingen uit, wat de standaard is: elke functie blijft ontgrendeld, iedereen krijgt GENERATION_QUOTA_PER_DAY gegenereerde routes per dag, en er wordt geen betaalprovider gecontacteerd. Laat BILLING_ENABLED=false staan, of zet het niet.

Ter referentie: dit zijn de variabelen die het gehoste product zet. Met BILLING_ENABLED=true weigert de API te starten tenzij het lanceermoment en alle drie de Stripe-waarden gezet zijn.

Achter een reverse proxy zettenCopy Anchor Link

De standaard-compose stelt poorten rechtstreeks beschikbaar. Voor TLS en een echt domein zet je een reverse proxy (Caddy, Traefik, ingress-nginx, Cloudflare Tunnel) voor de web- en api-services en override je de publieke URL's in .env:

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

PUBLIC_WEB_URL wordt ook gebruikt als OAuth-redirect-basis, dus die moet overeenkomen met wat je in Google Cloud hebt geconfigureerd.

UpgradenCopy Anchor Link

Maak eerst een databaseback-up (zie hieronder); migraties zijn alleen voorwaarts, dus een snapshot is je terugrol-pad. Daarna:

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

De API draait migraties automatisch bij het opstarten. Er is geen handmatige migratiestap. Om terug te rollen, herstel je de dump van voor de upgrade en pin je ROUTESS_TAG op de vorige release.

Back-up makenCopy Anchor Link

De Postgres-data staat in het named volume postgres_data. Standaard pg_dump werkt:

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

Herstel in een vers volume met psql:

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

ProbleemoplossingCopy Anchor Link

• Is de API gezond? curl http://localhost:3000/health/ready geeft 200 wanneer de API de database kan bereiken; /health/live controleert enkel of het proces draait.
• "address already in use" op :8080 of :3000: wijzig WEB_PORT / API_PORT in .env.
• Google-aanmelding geeft redirect_uri_mismatch: de geautoriseerde redirect-URI van de OAuth-client moet exact overeenkomen met <PUBLIC_WEB_URL>/auth/callback.
• Kaarttegels laden niet: controleer of VITE_MAPBOX_ACCESS_TOKEN is gezet; kijk in de browser-devtools naar 401's van api.mapbox.com.
• Verificatie-e-mails komen niet aan: zet RESEND_API_KEY en EMAIL_FROM. Zonder die logt de API de verificatie-URL naar stdout; draai docker compose logs api | grep '\[email:console\]'.