siop2/docs/06-production/runbook-dokploy.md

Runbook — déploiement Dokploy

Rôle de ce document (playbook) : la procédure REJOUABLE de mise en production sur Dokploy (PaaS auto-hébergé du partenaire), écrite en R0.13 et répétée à chaque release (principe « déployer tôt »). Statut : répété en local, en attente des accès au serveur du partenaire pour la première exécution réelle.

1. Topologie

Un projet Dokploy = un service « Compose » pointant sur ce dépôt, fichier infra/docker-compose.dokploy.yml :

domaine (Traefik/Dokploy) ──▶ siop2-web :80 (nginx, statique)
                                   │ /api/** (préfixe retiré)
                                   ▼
                              siop2-api :3000 (NestJS)
                                   │── siop2-postgres :5432 (pgvector + PostGIS)
                                   │── siop2-redis :6379
                                   └── siop2-minio :9000

• Convention siop2- (leçon v1) : le réseau Dokploy est partagé entre projets ; un service nommé postgres ou api collisionne. Tout est préfixé, sans exception.
• Seul siop2-web rejoint dokploy-network (réseau externe du reverse-proxy) : l'API n'est jamais exposée directement, elle est servie via le proxy /api de nginx — même topologie que le proxy Vite en dev, donc mêmes chemins partout.
• Les migrations Prisma s'appliquent au démarrage du conteneur API (prisma migrate deploy, idempotent) : la base est toujours au niveau du code déployé.

2. Variables d'environnement (à saisir dans Dokploy, jamais dans le dépôt)

Variable	Obligatoire	Rôle
POSTGRES_PASSWORD	✅	mot de passe PostgreSQL (générer : openssl rand -hex 24)
MINIO_ROOT_PASSWORD	✅	secret MinIO
JWT_SECRET	✅	signature des jetons (générer : openssl rand -hex 32)
POSTGRES_USER / POSTGRES_DB	—	défaut siop / siop
DEMO_MODE	—	absent en production client. true uniquement sur l'instance de démonstration
DEMO_MODE_I_KNOW	—	double verrou ADR-002 : requis si DEMO_MODE=true en production, sinon l'API refuse de démarrer
SEED_ON_START	—	true sur l'instance de démonstration : rôles, matrice et comptes démo au boot (idempotent)
SEED_DEMO_PASSWORD	—	mot de passe commun des comptes démo (défaut Demo!2026)

Profils types :

• Production client : les 4 dernières variables absentes. Les routes /auth/demo-accounts et /auth/demo-login n'existent pas (404, testé en CI).
• Instance de démonstration : DEMO_MODE=true, DEMO_MODE_I_KNOW=true, SEED_ON_START=true.

3. Première mise en production (checklist)

1. Dokploy → Create Project siop2 → Compose ; source = dépôt siop-spelev/siop2, branche main, fichier infra/docker-compose.dokploy.yml.
2. Renseigner les variables d'environnement (§2) dans l'onglet Environment.
3. Deploy. Dokploy construit les images (contexte = racine du dépôt, Dockerfiles apps/api et apps/web) puis démarre les 5 services ; l'API attend PostgreSQL/Redis/MinIO sains (healthchecks) et migre la base.
4. Onglet Domains du service siop2-web : associer le domaine (port 80, HTTPS Let's Encrypt géré par Dokploy).
5. Vérifications :
   • https://<domaine>/api/health → {"status":"ok", ...} (les 3 services up) ;
   • production client : https://<domaine>/api/auth/demo-accounts → 404 ;
   • instance démo : écran de connexion avec les 7 comptes, bascule de rôle < 3 s.
6. Consigner la mise en production dans docs/journal/journal.md (date, version, domaine).

4. Releases suivantes

git push sur main (CI verte exigée) → Dokploy Deploy (ou webhook auto-deploy). Les migrations de la release s'appliquent au démarrage ; en cas d'échec de migration, le conteneur s'arrête sans servir de trafic (l'ancienne version reste visible côté web).

5. Incidents & retours arrière

• Rollback applicatif : Dokploy → Deployments → redéployer le commit précédent. Les migrations Prisma étant additives (convention projet : jamais de DROP sans tâche dédiée validée), l'ancienne API fonctionne sur le schéma plus récent.
• API en échec au boot : docker logs siop2-api. Causes classiques : DEMO_MODE=true sans DEMO_MODE_I_KNOW (verrou ADR-002 — c'est voulu), DATABASE_URL erronée, migration échouée.
• Sauvegardes : volumes pg-data (base) et minio-data (fichiers). Sauvegarde PostgreSQL planifiée côté Dokploy (onglet Backups) — à configurer à la première mise en production réelle.

6. Répétition locale (sans Dokploy)

# depuis la racine — construit et lance les 5 services comme en production
docker network create dokploy-network 2>/dev/null || true
POSTGRES_PASSWORD=repetition MINIO_ROOT_PASSWORD=repetition-minio \
JWT_SECRET=$(openssl rand -hex 32) DEMO_MODE=true DEMO_MODE_I_KNOW=true SEED_ON_START=true \
docker compose -f infra/docker-compose.dokploy.yml up -d --build
# web : http://localhost via un port publié à ajouter ponctuellement, ou :
docker compose -f infra/docker-compose.dokploy.yml exec siop2-web wget -qO- http://localhost/api/health

C'est cette répétition (images construites, migrations au boot, parcours démo via nginx) qui a validé R0.13 en local — voir le journal du 15/07/2026.