Configuration reference
Every setting of an installation: default, who sets it and what it changes.
How settings are applied
Each service reads its settings when it starts. A launcher-created installation keeps them in workspace.env inside its private directory; a manual Compose installation keeps them in .env at the kit root. Neither file goes into Git.
After changing a value, apply it by rerunning the same launcher, or with docker compose ... up -d using the same files as before: Compose recreates the services whose configuration changed. An invalid value stops the service at startup with a message naming the setting.
The server launcher records its origin, certificate directory or proxy network, routing URL or routing configuration, dataset label and image in workspace.json. A rerun with different values is refused, and the existing configuration is preserved.
Application settings
| Setting | Default | Set by | What it does |
|---|---|---|---|
APP_MODE | local | Launcher, HTTPS overlay or .env | local: named accounts on loopback only. shared: named accounts over HTTPS; the HTTPS overlay forces it. local_demo is a legacy mode without sign-in that provisions a fictional company; never use it for company data. |
PUBLIC_ORIGIN | http://localhost:8000 | Launcher, HTTPS overlay or .env | The exact origin users open. Local modes accept only a localhost or 127.0.0.1 origin, for example http://localhost:8007; an IPv6 loopback origin is refused. Shared mode requires https://. No credentials, path or query. |
SETUP_TOKEN | empty | Launcher or .env | Private first-use code, at least 32 characters. It authorizes creating the first company, depot and administrator, and looking up the depot's address during that setup, only while the installation is empty. The launcher writes it into the private private-setup.url shortcut. |
MONITOR_TOKEN | empty | Operator | At least 32 characters. Enables GET /api/v1/metrics for a monitor sending it as a bearer token. Unset, the endpoint answers 404. |
TRUST_PROXY_CLIENT_HEADER | false | HTTPS and proxied overlays (true) | Shared mode only: use the X-VRP-Client header as the client address for sign-in limits. The bundled proxy overwrites that header on every request, also when it runs behind an existing HTTPS proxy. Behind another proxy without it, leave this off unless that proxy also overwrites the header. |
MAP_STYLE_URL | https://tiles.openfreemap.org/styles/liberty | Operator | Basemap style, HTTP(S) without credentials. Its origin is allowed by the page's security policy. Tile requests reveal the viewed area to that provider. |
VALHALLA_URL | Compose: http://host.docker.internal:8002. Host Python: http://127.0.0.1:8002 | Launcher, routing overlay or operator | Address of the Valhalla router as seen from the API and worker. An empty value means the default. The routing overlay sets http://valhalla:8002. |
ROUTING_DATASET | Geofabrik Ile-de-France downloaded 2026-09-22; static OSM speeds | Server launcher (--dataset) or operator | Description of the road data actually used: extract, date and speed assumptions. |
GEOCODER_URL | empty | Operator; the geocoder overlay sets http://addok:7878 | Address of the installation's own BAN geocoder, as seen from the API. When set, every company uses it, and Settings → Address search only names it. When empty, address lookup stays off unless an administrator turns on IGN's public service for their company on that page. HTTP(S) without credentials, query or fragment. A public service set here would receive every looked-up address, for every company: IGN's BAN service at https://data.geopf.fr/geocodage answers in the same format. |
GEOCODER_DATASET | Base Adresse Nationale (Licence Ouverte 2.0) | Operator | With GEOCODER_URL: source and date of the address data, shown next to the results as the licence requires, for example Base Adresse Nationale 2026-10-19 (Licence Ouverte 2.0). IGN's service chosen in Settings shows its own attribution. |
JOB_TIMEOUT_SECONDS | 180 (1–600) | Operator | Deadline for a whole calculation, including saving its result. The solver's search time shrinks to what remains after the routing matrices. |
MATRIX_CONCURRENCY | 1 (1–4) | Launcher (1) or operator | Routing matrix requests in flight at once. Raise it only together with routing workers and memory provisioned for it. |
MATRIX_MAX_KM | 200 (1–2000) | Operator | Longest straight-line distance between two points of one calculation, depots and start or end places included. Set it to the graph build's --max-matrix-km: a wider selection is refused before it is queued (AREA_TOO_WIDE). |
Three further settings exist for development and tests and are not passed by the Compose files: PORT (8000, which the Compose files and health check expect), DEMO_ORGANIZATION_ID (the identifier given to the installation's single company) and WEB_DIST (the built interface inside the image).
Company settings are not in these files: an administrator changes them in the application, under Settings (Delivery numbers, Address search, and Calculation for the safety margin before each window ends, 15 minutes by default), and the database keeps them. See the API reference.
Database credentials
| Setting | Default | What it does |
|---|---|---|
POSTGRES_DB | vrp | Database used by every service. A cutover to a restored copy changes it. |
POSTGRES_USER / POSTGRES_PASSWORD | vrp_owner / required | Bootstrap administration: setup, isolated restore and test operations only. |
MIGRATION_DB_USER / MIGRATION_DB_PASSWORD | vrp_migrator / required | Owns the schema and runs migrations, backups and retention commands. |
RUNTIME_DB_USER / RUNTIME_DB_PASSWORD | vrp_app / required | Used by the API and worker, with restricted privileges. |
POSTGRES_PORT | 5432 | Host loopback port of the database in the base Compose file. The launchers and the HTTPS overlay remove it. |
Use three distinct names and passwords; runtime and migration passwords need at least 20 characters. Launchers generate them. Changing POSTGRES_PASSWORD in an existing installation does not rotate it in the database volume. Setup does update the runtime and migration passwords: stop the API and worker before changing those, then restart them with the new values.
HTTPS overlay
| Setting | Default | What it does |
|---|---|---|
TLS_PUBLIC_ORIGIN | required | Exact HTTPS origin; becomes PUBLIC_ORIGIN for setup, API and worker. |
TLS_CERT_DIR | required | Absolute private directory holding fullchain.pem and privkey.pem, readable by the proxy user (UID 101). |
HTTPS_PORT | 8443 | Loopback port of the proxy. The VPS overlay publishes port 443 on all interfaces instead. |
Behind an existing HTTPS proxy
The proxied overlay deploy/docker-compose.proxied.yml replaces the HTTPS and VPS overlays on a server whose ports 80 and 443 belong to a reverse proxy, such as Coolify's Traefik. start_server.py --behind-proxy NETWORK writes these values; see Install on a VPS, step by step.
| Setting | Default | What it does |
|---|---|---|
TLS_PUBLIC_ORIGIN | required | Exact HTTPS origin; becomes PUBLIC_ORIGIN for setup, API and worker. |
PROXY_NETWORK | required | Docker network of the proxy, for example coolify. Only the edge web server joins it. |
PROXY_HOST | required | Hostname the proxy routes to the installation. |
PROXY_ROUTER | tournevia | Traefik router and service name; the launcher uses the installation's project name, tournevia-server-…, unique on the server. |
PROXY_HTTPS_ENTRYPOINT / PROXY_HTTP_ENTRYPOINT | https / http | Traefik entrypoints, Coolify's names. Dokploy uses websecure and web. HTTP requests are redirected to HTTPS. |
PROXY_CERT_RESOLVER | letsencrypt | Traefik certificate resolver. |
The edge server keeps the bundled limits and headers, serves plain HTTP on port 8080 of that network and publishes no port. It reaches the API through the alias tournevia-api, defined on the installation's own network only, since the bare service name could match a container on the shared proxy network; the kit's Compose and nginx files both carry that alias. The proxy must replace or append to X-Forwarded-For with the visitor's address, as Traefik and Caddy do; the last entry, from a private container address, is used for sign-in limits. A proxy other than Traefik ignores the labels and forwards the hostname to http://edge:8080 itself.
Routing overlay
| Setting | Default | What it does |
|---|---|---|
ROUTING_CONFIG | regional-matrix.json | Valhalla configuration, relative to deploy/runtime. |
ROUTING_THREADS | 2 | Router worker threads. |
ROUTING_MEMORY | 4g | Router memory limit. |
The overlay runs the router on an internal network that only the API and worker join, without a published port. start_server.py --routing-config region/valhalla.json adds it and writes these three values to workspace.env; on a server shared with other services, lower ROUTING_MEMORY, for example to 3g.
Geocoder overlay
| Setting | Default | What it does |
|---|---|---|
GEOCODER_MEMORY | 8g | Memory limit of the address index (Redis); addok needs at least 6 GB. |
GEOCODER_WORKERS | 2 | Geocoder worker processes. |
The overlay runs addok with the Base Adresse Nationale on an internal network that only the API joins, without a published port, with read-only containers and no request log. It sets GEOCODER_URL for the API.
Host development only
DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD and BIND_HOST (default 127.0.0.1) serve host-side Python only. Compose injects its own database values and sets BIND_HOST=0.0.0.0 inside the API container, whose host port stays on loopback.
Launcher options
start_local.py | Default | Use |
|---|---|---|
--directory | deploy/runtime/local-workspace | Private directory of the installation. |
--image | france-vrp-app:local | Built image, when creating the installation. |
--port | 8007 | Loopback port (1024–65535), when creating the installation. |
--upgrade-image NEW_IMAGE | — | Back up, then switch the existing installation to this image. |
--cutover-to DATABASE | — | Switch the existing installation to a validated restored database. |
start_server.py | Default | Use |
|---|---|---|
--directory | required | Private directory of the installation. |
--origin | required | HTTPS hostname on port 443, without credentials, path or query. |
--certificates | this or --behind-proxy | Directory containing fullchain.pem and privkey.pem; the bundled proxy publishes port 443. |
--behind-proxy NETWORK | this or --certificates | Docker network of an HTTPS proxy that already serves the server, such as coolify. |
--valhalla-url | this or --routing-config | Private Valhalla base URL of a separately run router. |
--routing-config PATH | this or --valhalla-url | Valhalla configuration under deploy/runtime, for example region/valhalla.json; the router runs inside the installation. |
--dataset | required | Actual extract, date and speed assumptions. |
--image | france-vrp-app:local | Built image. |
--prepare-only | — | Validate the merged configuration without starting containers or opening ports. |
--upgrade-image NEW_IMAGE | — | Back up, stop API and worker, then start with this image. |
--cutover-to DATABASE | — | Switch the existing installation to a validated restored database. |
The origin, one of --certificates or --behind-proxy, one of --valhalla-url or --routing-config, and the dataset are needed for a new installation and for each ordinary rerun, with the recorded values. --upgrade-image and --cutover-to need an existing installation and cannot be combined in one run. See Upgrade and Backup and restore.
Files in the private directory
| File | Content |
|---|---|
workspace.env | Generated secrets and settings, created readable by its owner only. |
workspace.json | Docker project name, origin, current image and, after an upgrade, the previous image. |
image.json | The image used by setup, API and worker. |
workspace.yml | Local installations only: loopback port binding, no database port. |
private-setup.url | Private first-use shortcut; never share it with dispatchers. |
backups/ | Archives written by --upgrade-image. |
On Windows, these files inherit the access rights of their folder: choose a folder only operators can read.