Initial local backup snapshot

2026-06-24 00:02:55 -03:00 · 2026-06-24 00:02:55 -03:00 · acd9e14ba5
commit acd9e14ba5
367 changed files with 118038 additions and 0 deletions
--- a/docs/runtime-health-maintenance.md
+++ b/docs/runtime-health-maintenance.md
@ -0,0 +1,127 @@
+# 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 :
+
+```bash
+./scripts/maintenance-flag.sh on
+./scripts/maintenance-flag.sh off
+./scripts/maintenance-flag.sh status
+```
+
+Sur le VPS :
+
+```bash
+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 :
+
+```bash
+./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 :
+
+```bash
+USE_MAINTENANCE_FLAG=1 ./scripts/deploy-vps.sh prod
+```
+
+## Monitoring simple
+
+Verifier plusieurs fois un endpoint :
+
+```bash
+./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 :
+
+```bash
+./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.