Incidents et runbooks

L’objectif initial n’est pas d’expliquer toute la cause, mais de limiter l’impact sans détruire les preuves ni aggraver les données.

Sévérité

Niveau	Exemple	Réponse
SEV-1	production inaccessible, perte ou corruption probable	action immédiate, gel des changements, communication fréquente
SEV-2	fonction majeure indisponible, contournement limité	prise en charge prioritaire et suivi régulier
SEV-3	dégradation localisée ou intégration externe	correction planifiée, surveillance
SEV-4	anomalie sans impact utilisateur immédiat	ticket et traitement normal

Adaptez la sévérité à l’impact réel, au nombre d’utilisateurs, à la durée et au risque sur les données, pas seulement au caractère impressionnant d’une trace.

Première réponse

1. Notez heure de détection, environnement, domaine, SHA et dernier changement connu.
2. Désignez un responsable de l’incident.
3. Gelez les déploiements non liés.
4. Déterminez si les données sont en danger ; bloquez les écritures concernées si nécessaire.
5. Capturez logs assainis, état des conteneurs et métriques avant redémarrage.
6. Choisissez contention, rollback ou restauration selon le type de changement.
7. Communiquez impact, contournement et prochain point, sans spéculer.

Arbre de diagnostic

Le domaine répond-il ?
├─ non → DNS → certificat → Traefik/Dokploy → conteneur → port
└─ oui
   ├─ 502/504 → processus, bind 0.0.0.0, port interne, réseau, health check
   ├─ 5xx → logs application, configuration, migration, dépendance externe
   ├─ page vide/SSR → web, API_BASE_URL, contrat backend
   └─ fonction isolée → autorisation, donnée, e-mail/calendrier/média/IA

Runbook : Bad Gateway backend

1. Confirmez que le conteneur est en cours d’exécution, pas seulement construit.
2. Lisez les dernières lignes de démarrage et recherchez une configuration invalide.
3. Vérifiez que le processus écoute sur 0.0.0.0:8090.
4. Testez /api/health depuis le réseau interne.
5. Contrôlez le port configuré dans le domaine Dokploy.
6. Vérifiez droits et montage de /app/pb_data.
7. Si l’image précédente fonctionne avec le même volume, évaluez un rollback de code.

Runbook : certificat invalide ou expiré

1. Relevez le certificat effectivement présenté et l’heure du serveur.
2. Vérifiez A/AAAA et l’absence d’ancienne IP.
3. Contrôlez l’accès public aux ports 80/443.
4. Lisez les erreurs ACME de Traefik et identifiez domaine, challenge et limite éventuelle.
5. Corrigez DNS/routage/permissions, puis relancez un renouvellement ciblé.

Runbook : web indisponible, backend sain

1. Testez le health backend depuis l’extérieur puis depuis le conteneur web.
2. Vérifiez API_BASE_URL, DNS interne et certificat amont.
3. Cherchez une incompatibilité entre SHA web et contrat backend.
4. Inspectez les logs SSR ; un navigateur peut recevoir une erreur rendue côté serveur.
5. Contrôlez le runtime/adaptateur, le port et la commande de démarrage du web.
6. Revenez au dernier SHA web sain si aucune donnée n’est impliquée.

Runbook : volume ou base

Si le backend démarre avec une base vide, arrêtez les écritures immédiatement. Vérifiez le montage du volume avant toute création de données. Ne copiez pas une base de production par-dessus le volume actuel sans conserver ce dernier et sans tester la restauration dans un volume isolé.

En cas d’erreur SQLite : contrôlez espace disque, droits UID 1000, fichiers du volume et derniers événements. Un redémarrage répété peut masquer le premier message utile.

Runbook : e-mails en échec

1. Vérifiez que la demande a bien été persistée.
2. Consultez le statut et la dernière erreur d’envoi, sans exposer le contenu personnel.
3. Contrôlez configs/email, DNS et disponibilité SMTP.
4. Corrigez la cause puis utilisez la relivraison prévue par le back-office.
5. Évitez de recréer la demande, ce qui peut produire des doublons.

Clôture

Un incident est clos après rétablissement, fenêtre de surveillance et consignation de :

• impact et durée ;
• chronologie factuelle ;
• cause technique et facteurs contributifs ;
• données perdues ou non, clairement établies ;
• action de restauration/rollback ;
• mesures empêchant la récidive, avec propriétaires et échéances.

Le post-mortem ne cherche pas un coupable. Il doit améliorer les garde-fous, alertes, tests, sauvegardes ou procédures qui auraient réduit l’impact.