Operations and upgrades

Identify the installationCopy Anchor Link

Keep the launcher's private directory: workspace.json identifies the Docker project, workspace.env holds secrets and image.json selects the image. Never commit these files. Keep a secure copy away from the host.

Run these commands from the kit matching the currently installed version, with Python dependencies from backend/requirements-dev.txt. Replace PRIVATE_PATH with that installation's private directory.

Back up and verify recoveryCopy Anchor Link

Wait for calculations to finish and pause new changes:

python scripts/database_backup.py --workspace PRIVATE_PATH backup --output backups/before-upgrade.dump
python scripts/database_backup.py --workspace PRIVATE_PATH restore backups/before-upgrade.dump

The backup selects that workspace's project and database, refuses to overwrite a file and checks that the schema matches the application. Login sessions are excluded. Recovery creates a new isolated database and prints its name; it never replaces the live database. After validating the copy, switch to it with the launcher’s --cutover-to option.

Copy archives to independent private storage. Scheduling, encryption, pruning, cutover and data erasure are described in Backup and restore.

Upgrade the applicationCopy Anchor Link

Let current work finish, then run one command with the newly built image:

python3 scripts/start_server.py --directory PRIVATE_PATH --upgrade-image NEW_IMAGE

start_local.py accepts the same option for a local workspace. The launcher checks that the image exists, writes a backup to PRIVATE_PATH/backups/before-upgrade-*.dump, stops the API and worker, records the new and previous image, and starts the stack. Setup runs the migrations first; if it fails, the API and worker stay stopped and the database is preserved. Some migrations need an action in the application after the upgrade, such as setting the vehicles' weekly hours: see Upgrade.

Verify sign-in, account language, existing data and a representative calculation before reopening access. Never delete volumes or repeat first-time provisioning to upgrade. Backout and the manual procedure for a non-launcher Compose installation are in Upgrade.

Monitoring and alertsCopy Anchor Link

Set MONITOR_TOKEN (at least 32 random characters) to enable GET /api/v1/metrics: Prometheus text metrics for a monitor that sends Authorization: Bearer <token>. Without the setting the endpoint does not exist (404). It is independent of user accounts and reports installation-wide counts only, never delivery or user data: database readiness, worker and routing state, queued and running calculations, the oldest wait, successes and failures in the last hour, and the age of the last successful calculation. The metrics are named tournevia_*, for example tournevia_database_ready and tournevia_jobs_queued.

scrape_configs:
  - job_name: tournevia
    scheme: https
    metrics_path: /api/v1/metrics
    authorization: { type: Bearer, credentials_file: /etc/prometheus/tournevia-token }
    static_configs: [{ targets: ['planner.example.com'] }]

The kit’s deploy/prometheus-alerts.example.yml holds starting alert rules: planner unreachable, database not ready, worker stopped, routing unavailable, calculations waiting over ten minutes and repeated failures. They use the new metric names and expect the scrape job above, named tournevia. Add disk-space and backup-age alerts from the host’s own exporter.

HTTPS and routing operationsCopy Anchor Link

Renew certificates before expiry. After verifying the certificate and key, restart only the HTTPS proxy with this installation's Compose configuration. The key must stay readable by the proxy (UID 101) with restricted permissions.

Monitor failed calculation identifiers, disk space, backups and routing availability. A visible basemap does not prove that routing works. Identify replacement routing data by extract and date.

Before operational useCopy Anchor Link

Documentation does not replace installation/recovery checks, a private security channel or a supervised pilot. Verify actual constraints and routes before recommending operational use. See Security.

Build a candidate kitCopy Anchor Link

This step is for maintainers preparing a distribution, not dispatchers joining an existing instance.

1. Start from a clean, tested, committed application checkout.
2. Choose the candidate version and run the packaging command below.
3. Sign the ZIP with the release signer’s SSH key; after an image build, also sign its software bills of materials.
4. Distribute the ZIP, its SHA-256 sidecar and its .sig through your trusted channel, and publish the signer’s public key through an independent one. The kit excludes secrets, databases and routing graphs.
5. Verify installation and recovery from the resulting kit before treating it as a supported release.

python scripts/release.py pack --version 0.8.0-rc.1
python scripts/release.py sign --key ~/.ssh/tournevia-release deploy/runtime/releases/france-vrp-0.8.0-rc.1-REVISION.zip

Signing writes FILE.sig next to each file; it never creates keys or overwrites a signature. Recipients check it with ssh-keygen -Y verify, an allowed_signers file and the namespace tournevia-release (-n tournevia-release) before extracting. release.py build also writes two CycloneDX software bills of materials to deploy/runtime/sbom: the image’s Debian and Python packages, and the frontend’s production npm packages. Container images are built locally and not published, so no image signature is produced.

The version above is an example candidate label, not an announcement of a published release.