Auto-hébergement

Ce guide pas à pas met une instance routess en route sur ta propre machine ou ton serveur en environ cinq minutes. Pour Kubernetes, voir Kubernetes.

Ce dont tu as besoinCopy Anchor Link

• Docker et Docker Compose v2 (un Docker Desktop moderne ou Docker Engine est livré avec les deux).
• Un client Google OAuth pour la connexion Google (le fichier compose l'exige). Les utilisateurs peuvent aussi se connecter avec e-mail + mot de passe une fois la stack en place.
• Un token d'accès Mapbox ; le tier gratuit suffit.
• Un moteur de routage Valhalla (VALHALLA_URL). Le calcul d'itinéraire et l'analyse de surface passent par lui ; sans lui, les endpoints de routage renvoient 503.
• Des chaînes aléatoires longues pour JWT_SECRET, ANALYTICS_SALT, PAT_PEPPER et DB_PASSWORD. Génère-les avec openssl rand -base64 32.

Optionnels, désactivés proprement quand non définis :

• Resend pour les e-mails transactionnels (sans lui, les URL de vérification sont écrites sur stdout).
• Sentry / GlitchTip pour le reporting d'erreurs du navigateur.
• Umami pour l'analytics produit.
• Rôle admin pour accéder au panneau d'administration intégré à l'application.

Configurer Google OAuthCopy Anchor Link

1. Ouvre la page des identifiants de la Google Cloud Console.
2. Crée un OAuth 2.0 Client ID de type Web application.
3. Sous Authorized JavaScript origins, ajoute l'URL que tes utilisateurs ouvriront (par ex. http://localhost:8080 ou https://routess.example.com).
4. Sous Authorized redirect URIs, ajoute <your-web-url>/auth/callback.
5. Copie le Client ID et le Client secret.

Obtenir un token MapboxCopy Anchor Link

1. Inscris-toi sur account.mapbox.com.
2. Crée un token d'accès public (pk.…) sous Access tokens.
3. Restreins-le à ton domaine quand tu passes en production.

Le lancerCopy 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

Ouvre ensuite http://localhost:8080.

La stack démarre quatre conteneurs :

Change les ports hôtes via WEB_PORT, API_PORT, DOCS_PORT dans .env.

Figer une versionCopy Anchor Link

Le tag par défaut est latest. Pour la production, fige une release précise :

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

Ou définis ROUTESS_TAG dans .env. Voir la page des releases pour les tags disponibles.

Variables d'environnementCopy Anchor Link

Le fichier .env dans docker/.env.selfhost.example fait foi. Les variables que tu manipuleras le plus souvent :

Variables avancéesCopy Anchor Link

L'API comprend plus de réglages que ce que le fichier compose transmet. Pour en utiliser un, ajoute-le sous le service api dans environment dans docker/compose.selfhost.yaml (ou ton propre fichier de surcharge) :

Pour le conteneur web :

Le logging de la console du navigateur est par défaut à warn. Pour déboguer un seul navigateur, mets localStorage["routess:log-level"] à debug, info, warn, error ou none et recharge.

Paiement (produit hébergé uniquement)Copy Anchor Link

Routess.com vend un pass Pro annuel (ADR 0039). Une instance auto-hébergée laisse le paiement désactivé, c'est le défaut : toutes les fonctionnalités restent débloquées, tout le monde a droit à GENERATION_QUOTA_PER_DAY routes générées par jour, et aucun prestataire de paiement n'est contacté. Laisse BILLING_ENABLED=false, ou ne le définis pas.

Pour référence, voici les variables que définit le produit hébergé. Avec BILLING_ENABLED=true, l'API refuse de démarrer tant que le moment du lancement et les trois valeurs Stripe ne sont pas définis.

Le mettre derrière un reverse proxyCopy Anchor Link

Le compose par défaut expose les ports directement. Pour le TLS et un vrai domaine, place les services web et api derrière un reverse proxy (Caddy, Traefik, ingress-nginx, Cloudflare Tunnel) et surcharge les URL publiques dans .env :

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

PUBLIC_WEB_URL est aussi utilisé comme base de redirection OAuth, il doit donc correspondre à ce que tu as configuré dans Google Cloud.

Mettre à jourCopy Anchor Link

Fais d'abord une sauvegarde de la base de données (voir ci-dessous) ; les migrations sont uniquement en avant, donc un snapshot est ton chemin de rollback. Ensuite :

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

L'API exécute les migrations automatiquement au démarrage. Il n'y a pas d'étape de migration manuelle. Pour revenir en arrière, restaure le dump d'avant mise à jour et fige ROUTESS_TAG sur la release précédente.

SauvegarderCopy Anchor Link

Les données Postgres vivent dans le volume nommé postgres_data. Un pg_dump standard fonctionne :

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

Restaure dans un volume frais avec psql :

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

DépannageCopy Anchor Link

• L'API est-elle en bonne santé ? curl http://localhost:3000/health/ready renvoie 200 quand l'API peut atteindre la base de données ; /health/live vérifie seulement que le processus est actif.
• « address already in use » sur :8080 ou :3000 : change WEB_PORT / API_PORT dans .env.
• La connexion Google renvoie redirect_uri_mismatch : l'URI de redirection autorisée du client OAuth doit correspondre exactement à <PUBLIC_WEB_URL>/auth/callback.
• Les tuiles de carte ne se chargent pas : vérifie que VITE_MAPBOX_ACCESS_TOKEN est défini ; regarde les devtools du navigateur pour des 401 venant de api.mapbox.com.
• Les e-mails de vérification n'arrivent pas : définis RESEND_API_KEY et EMAIL_FROM. Sans eux, l'API écrit l'URL de vérification sur stdout ; lance docker compose logs api | grep '\[email:console\]'.