# 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.