Référence de configuration
Chaque paramètre d’une installation : valeur par défaut, qui le définit et ce qu’il change.
Application des paramètres
Chaque service lit ses paramètres au démarrage. Une installation créée par le lanceur les conserve dans workspace.env, dans son dossier privé ; une installation Compose manuelle les conserve dans .env, à la racine du kit. Aucun de ces fichiers ne va sur GitHub.
Après une modification, appliquez-la en relançant le même lanceur, ou avec docker compose ... up -d et les mêmes fichiers qu’auparavant : Compose recrée les services dont la configuration a changé. Une valeur invalide arrête le service au démarrage avec un message qui nomme le paramètre.
Le lanceur serveur enregistre l’origine, le dossier des certificats ou le réseau du proxy, l’adresse ou la configuration de routage, le libellé des données et l’image dans workspace.json. Une relance avec d’autres valeurs est refusée et la configuration existante est conservée.
Paramètres de l’application
| Paramètre | Valeur par défaut | Défini par | Effet |
|---|---|---|---|
APP_MODE | local | Lanceur, surcouche HTTPS ou .env | local : comptes nominatifs sur la boucle locale uniquement. shared : comptes nominatifs en HTTPS ; la surcouche HTTPS l’impose. local_demo est un ancien mode sans connexion qui crée une entreprise fictive ; ne l’utilisez jamais pour des données d’entreprise. |
PUBLIC_ORIGIN | http://localhost:8000 | Lanceur, surcouche HTTPS ou .env | L’origine exacte ouverte par les utilisateurs. Les modes locaux n’acceptent qu’une origine localhost ou 127.0.0.1, par exemple http://localhost:8007 ; une origine de boucle locale IPv6 est refusée. Le mode partagé exige https://. Ni identifiants, ni chemin, ni paramètres. |
SETUP_TOKEN | vide | Lanceur ou .env | Code privé de première utilisation, d’au moins 32 caractères. Il autorise la création de la première entreprise, du dépôt et de l’administrateur, ainsi que la recherche de l’adresse du dépôt pendant cette configuration, seulement tant que l’installation est vide. Le lanceur l’inscrit dans le raccourci privé private-setup.url. |
MONITOR_TOKEN | vide | Opérateur | Au moins 32 caractères. Active GET /api/v1/metrics pour un outil de supervision qui l’envoie comme jeton Bearer. Sans lui, la route répond 404. |
TRUST_PROXY_CLIENT_HEADER | false | Surcouches HTTPS et derrière un proxy (true) | Mode partagé uniquement : utiliser l’en-tête X-VRP-Client comme adresse du client pour les limites de connexion. Le proxy fourni écrase cet en-tête à chaque requête, y compris lorsqu’il fonctionne derrière un proxy HTTPS existant. Derrière un autre proxy sans lui, laissez-le désactivé, sauf si ce proxy écrase aussi l’en-tête. |
MAP_STYLE_URL | https://tiles.openfreemap.org/styles/liberty | Opérateur | Style du fond de carte, en HTTP(S) sans identifiants. Son origine est autorisée par la politique de sécurité de la page. Les requêtes de tuiles révèlent la zone consultée à ce fournisseur. |
VALHALLA_URL | Compose : http://host.docker.internal:8002. Python sur l’hôte : http://127.0.0.1:8002 | Lanceur, surcouche de routage ou opérateur | Adresse du routeur Valhalla vue depuis l’API et le worker. Une valeur vide vaut la valeur par défaut. La surcouche de routage impose http://valhalla:8002. |
ROUTING_DATASET | Geofabrik Ile-de-France downloaded 2026-09-22; static OSM speeds | Lanceur serveur (--dataset) ou opérateur | Description des données routières réellement utilisées : extrait, date et hypothèses de vitesse. |
GEOCODER_URL | vide | Opérateur ; la surcouche de géocodage impose http://addok:7878 | Adresse du géocodeur BAN propre à l’installation, vue depuis l’API. Définie, elle sert à toutes les entreprises, et Paramètres → Recherche d’adresses ne fait que la nommer. Vide, la recherche d’adresses reste désactivée, sauf si un administrateur active sur cette page le service public de l’IGN pour son entreprise. HTTP(S) sans identifiants, paramètres ni fragment. Un service public indiqué ici recevrait chaque adresse recherchée, pour toutes les entreprises : le service BAN de l’IGN, https://data.geopf.fr/geocodage, répond dans le même format. |
GEOCODER_DATASET | Base Adresse Nationale (Licence Ouverte 2.0) | Opérateur | Avec GEOCODER_URL : source et date des données d’adresses, affichées à côté des résultats comme l’exige la licence, par exemple Base Adresse Nationale 2026-10-19 (Licence Ouverte 2.0). Le service de l’IGN choisi dans les paramètres affiche sa propre attribution. |
JOB_TIMEOUT_SECONDS | 180 (1–600) | Opérateur | Délai d’un calcul complet, enregistrement du résultat compris. Le temps de recherche du solveur se réduit à ce qui reste après les matrices de routage. |
MATRIX_CONCURRENCY | 1 (1–4) | Lanceur (1) ou opérateur | Nombre de requêtes de matrices de routage simultanées. Ne l’augmentez qu’avec des workers de routage et une mémoire prévus pour cela. |
MATRIX_MAX_KM | 200 (1–2000) | Opérateur | Plus grande distance à vol d’oiseau entre deux points d’un même calcul, dépôts et lieux de départ ou d’arrivée compris. Donnez-lui la valeur --max-matrix-km de la construction du graphe : une sélection plus étendue est refusée avant sa mise en file d’attente (AREA_TOO_WIDE). |
Trois autres paramètres existent pour le développement et les tests et ne sont pas transmis par les fichiers Compose : PORT (8000, attendu par les fichiers Compose et le contrôle de santé), DEMO_ORGANIZATION_ID (l’identifiant attribué à l’unique entreprise de l’installation) et WEB_DIST (l’interface construite dans l’image).
Les paramètres de l’entreprise ne figurent pas dans ces fichiers : un administrateur les modifie dans l’application, sous Paramètres (Numéros de livraison, Recherche d’adresses, et Calcul pour la marge de sécurité avant la fin de chaque créneau, 15 minutes par défaut), et la base de données les conserve. Voir la référence API.
Identifiants de la base de données
| Paramètre | Valeur par défaut | Effet |
|---|---|---|
POSTGRES_DB | vrp | Base utilisée par tous les services. Une bascule vers une copie restaurée la modifie. |
POSTGRES_USER / POSTGRES_PASSWORD | vrp_owner / obligatoire | Administration initiale : setup, restauration isolée et opérations de test uniquement. |
MIGRATION_DB_USER / MIGRATION_DB_PASSWORD | vrp_migrator / obligatoire | Propriétaire du schéma ; exécute migrations, sauvegardes et commandes de conservation. |
RUNTIME_DB_USER / RUNTIME_DB_PASSWORD | vrp_app / obligatoire | Utilisé par l’API et le worker, avec des droits restreints. |
POSTGRES_PORT | 5432 | Port de la base sur la boucle locale de l’hôte dans le fichier Compose de base. Les lanceurs et la surcouche HTTPS le suppriment. |
Utilisez trois noms et trois mots de passe distincts ; les mots de passe d’exécution et de migration comptent au moins 20 caractères. Les lanceurs les génèrent. Modifier POSTGRES_PASSWORD sur une installation existante ne le change pas dans le volume de la base. Setup met en revanche à jour les mots de passe d’exécution et de migration : arrêtez l’API et le worker avant de les changer, puis redémarrez-les avec les nouvelles valeurs.
Surcouche HTTPS
| Paramètre | Valeur par défaut | Effet |
|---|---|---|
TLS_PUBLIC_ORIGIN | obligatoire | Origine HTTPS exacte ; devient PUBLIC_ORIGIN pour setup, l’API et le worker. |
TLS_CERT_DIR | obligatoire | Dossier privé absolu contenant fullchain.pem et privkey.pem, lisibles par l’utilisateur du proxy (UID 101). |
HTTPS_PORT | 8443 | Port du proxy sur la boucle locale. La surcouche VPS publie à la place le port 443 sur toutes les interfaces. |
Derrière un proxy HTTPS existant
La surcouche deploy/docker-compose.proxied.yml remplace les surcouches HTTPS et VPS sur un serveur dont les ports 80 et 443 appartiennent à un proxy inverse, comme le Traefik de Coolify. start_server.py --behind-proxy RÉSEAU écrit ces valeurs ; voir Installer sur un VPS, pas à pas.
| Paramètre | Valeur par défaut | Effet |
|---|---|---|
TLS_PUBLIC_ORIGIN | obligatoire | Origine HTTPS exacte ; devient PUBLIC_ORIGIN pour setup, l’API et le worker. |
PROXY_NETWORK | obligatoire | Réseau Docker du proxy, par exemple coolify. Seul le serveur web edge le rejoint. |
PROXY_HOST | obligatoire | Nom d’hôte que le proxy dirige vers l’installation. |
PROXY_ROUTER | tournevia | Nom du routeur et du service Traefik ; le lanceur utilise le nom de projet de l’installation, tournevia-server-…, unique sur le serveur. |
PROXY_HTTPS_ENTRYPOINT / PROXY_HTTP_ENTRYPOINT | https / http | Points d’entrée Traefik, noms de Coolify. Dokploy utilise websecure et web. Les requêtes HTTP sont redirigées vers HTTPS. |
PROXY_CERT_RESOLVER | letsencrypt | Résolveur de certificats Traefik. |
Le serveur edge conserve les limites et les en-têtes du proxy fourni, sert du HTTP simple sur le port 8080 de ce réseau et ne publie aucun port. Il joint l’API par l’alias tournevia-api, défini sur le seul réseau propre à l’installation, car le simple nom du service pourrait désigner un conteneur du réseau partagé du proxy ; les fichiers Compose et nginx du kit portent tous deux cet alias. Le proxy doit remplacer X-Forwarded-For par l’adresse du visiteur ou l’y ajouter, comme le font Traefik et Caddy ; la dernière entrée, venant d’une adresse privée de conteneur, sert aux limites de connexion. Un proxy autre que Traefik ignore les étiquettes et transmet lui-même le nom d’hôte à http://edge:8080.
Surcouche de routage
| Paramètre | Valeur par défaut | Effet |
|---|---|---|
ROUTING_CONFIG | regional-matrix.json | Configuration Valhalla, relative à deploy/runtime. |
ROUTING_THREADS | 2 | Nombre de threads du routeur. |
ROUTING_MEMORY | 4g | Limite de mémoire du routeur. |
La surcouche exécute le routeur sur un réseau interne que seuls l’API et le worker rejoignent, sans port publié. start_server.py --routing-config region/valhalla.json l’ajoute et écrit ces trois valeurs dans workspace.env ; sur un serveur partagé avec d’autres services, abaissez ROUTING_MEMORY, par exemple à 3g.
Surcouche de géocodage
| Paramètre | Valeur par défaut | Effet |
|---|---|---|
GEOCODER_MEMORY | 8g | Limite de mémoire de l’index des adresses (Redis) ; addok demande au moins 6 Go. |
GEOCODER_WORKERS | 2 | Nombre de processus du géocodeur. |
La surcouche exécute addok avec la Base Adresse Nationale sur un réseau interne que seule l’API rejoint, sans port publié, avec des conteneurs en lecture seule et sans journal des requêtes. Elle définit GEOCODER_URL pour l’API.
Développement sur l’hôte uniquement
DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD et BIND_HOST (par défaut 127.0.0.1) servent uniquement au Python lancé sur l’hôte. Compose injecte ses propres valeurs de base de données et fixe BIND_HOST=0.0.0.0 dans le conteneur de l’API, dont le port reste publié sur la boucle locale de l’hôte.
Options des lanceurs
start_local.py | Valeur par défaut | Usage |
|---|---|---|
--directory | deploy/runtime/local-workspace | Dossier privé de l’installation. |
--image | france-vrp-app:local | Image construite, à la création de l’installation. |
--port | 8007 | Port de la boucle locale (1024–65535), à la création de l’installation. |
--upgrade-image NOUVELLE_IMAGE | — | Sauvegarder, puis passer l’installation existante sur cette image. |
--cutover-to BASE | — | Basculer l’installation existante vers une base restaurée et vérifiée. |
start_server.py | Valeur par défaut | Usage |
|---|---|---|
--directory | obligatoire | Dossier privé de l’installation. |
--origin | obligatoire | Nom d’hôte HTTPS sur le port 443, sans identifiants, chemin ni paramètres. |
--certificates | ceci ou --behind-proxy | Dossier contenant fullchain.pem et privkey.pem ; le proxy fourni publie le port 443. |
--behind-proxy RÉSEAU | ceci ou --certificates | Réseau Docker d’un proxy HTTPS qui dessert déjà le serveur, comme coolify. |
--valhalla-url | ceci ou --routing-config | Adresse privée de base d’un routeur Valhalla exécuté à part. |
--routing-config CHEMIN | ceci ou --valhalla-url | Configuration Valhalla sous deploy/runtime, par exemple region/valhalla.json ; le routeur s’exécute dans l’installation. |
--dataset | obligatoire | Extrait réel, date et hypothèses de vitesse. |
--image | france-vrp-app:local | Image construite. |
--prepare-only | — | Valider la configuration fusionnée sans démarrer de conteneur ni ouvrir de port. |
--upgrade-image NOUVELLE_IMAGE | — | Sauvegarder, arrêter l’API et le worker, puis démarrer avec cette image. |
--cutover-to BASE | — | Basculer l’installation existante vers une base restaurée et vérifiée. |
L’origine, --certificates ou --behind-proxy, --valhalla-url ou --routing-config, et le libellé des données sont nécessaires pour une nouvelle installation et pour chaque relance ordinaire, avec les valeurs enregistrées. --upgrade-image et --cutover-to exigent une installation existante et ne peuvent pas être combinées dans une même exécution. Consultez Mise à jour et Sauvegarde et restauration.
Fichiers du dossier privé
| Fichier | Contenu |
|---|---|
workspace.env | Secrets et paramètres générés, créés lisibles par leur seul propriétaire. |
workspace.json | Nom du projet Docker, origine, image actuelle et, après une mise à jour, l’image précédente. |
image.json | L’image utilisée par setup, l’API et le worker. |
workspace.yml | Installations locales uniquement : publication sur la boucle locale, aucun port de base de données. |
private-setup.url | Raccourci privé de première utilisation ; ne le communiquez jamais aux exploitants. |
backups/ | Archives écrites par --upgrade-image. |
Sous Windows, ces fichiers héritent des droits d’accès de leur dossier : choisissez un dossier lisible par les seuls opérateurs.