portail-associations/docs/runtime-health-maintenance.md

Runtime health, maintenance et redemarrage propre

Ce document formalise la passe d'exploitation qui evite les redemarrages "a l'aveugle" et structure les verifications.

Endpoints

• GET /health/live
  • confirme que le processus Express est vivant
  • retourne 503 uniquement pendant l'arret en douceur
• GET /health/ready
  • confirme que l'application est vraiment exploitable
  • verifie :
    • fin du delai de demarrage
    • etat runtime pret
    • base disponible si configuree
    • absence d'arret en cours
• GET /health
  • alias pratique vers GET /health/ready

Mode maintenance

Le mode maintenance repose sur un drapeau fichier persistant :

• chemin par defaut : /app/uploads/system/maintenance.flag

Quand le drapeau existe :

• les pages HTML publiques et internes renvoient une page legere de maintenance
• les endpoints /health*, /api* et /uploads/* restent accessibles

Commandes utiles

Depuis le projet :

./scripts/maintenance-flag.sh on
./scripts/maintenance-flag.sh off
./scripts/maintenance-flag.sh status

Sur le VPS :

ssh ovh-vps 'cd /home/ubuntu/portail-associations && MAINTENANCE_FLAG_PATH=/home/ubuntu/portail-associations/uploads/system/maintenance.flag ./scripts/maintenance-flag.sh on'

Deploiement propre

Le script officiel :

./scripts/deploy-vps.sh preprod
./scripts/deploy-vps.sh prod

Verifie maintenant :

1. le SSH
2. le check TypeScript
3. le build local
4. la synchro
5. le redeploiement Docker
6. le retour 200 sur /health/ready
7. le retour 200 sur la home

Option maintenance

Pour entourer le deploiement d'une page de maintenance :

USE_MAINTENANCE_FLAG=1 ./scripts/deploy-vps.sh prod

Monitoring simple

Verifier plusieurs fois un endpoint :

./scripts/monitor-http-health.sh https://www.portail-association973.com/health/ready

Le script remonte notamment les 502 et 503.

Industrialisation CI/CD

Le minimum utile pour la chaine de deploiement est :

1. lancer corepack pnpm check
2. lancer corepack pnpm build
3. deployer
4. attendre GET /health/ready = 200
5. verifier la home
6. lancer un mini monitoring post-deploiement sur 1 a 2 minutes

Exemple de sequence :

./scripts/deploy-vps.sh preprod
./scripts/monitor-http-health.sh https://preprod.portail-association973.com/health/ready

Alerting simple

Sans ajouter de grosse brique tout de suite, on peut deja alerter proprement si :

• /health/ready ne revient pas en 200
• plus d'un 502 ou 503 apparait pendant la fenetre de verification
• le mode maintenance reste actif par erreur

La premiere etape rentable est de brancher ces controles dans la routine de deploiement ou dans un cron d'observation.

Limite honnete

Avec un seul conteneur applicatif et une recreation Docker classique, le risque de micro-coupure n'est pas totalement elimine.

Cette passe :

• fiabilise la detection du "pret"
• ajoute un arret plus propre
• structure la maintenance
• rend les controles repetables

Pour viser le zero 502 strict, il faudra ensuite une architecture de bascule plus poussee :

• blue/green
• double instance applicative
• ou proxy avec vraie page de maintenance en amont.