Niveau 🟡 intermédiaire
Durée estimée : 20 min · Prérequis : Mises à jour : procédure sans casse
Un runbook, c'est la fiche de procédure d'urgence affichée près d'un tableau électrique : pas un
roman explicatif à lire pendant que les lumières sont coupées, mais une suite d'étapes précises,
écrites à froid, pour quelqu'un de stressé ou fatigué qui doit agir vite et sans se souvenir de
tout par cœur.
Un runbook est une procédure écrite, étape par étape, pour diagnostiquer et résoudre un
incident précis et récurrent — pensée pour être suivie pendant l'incident, pas pour être
comprise en profondeur à ce moment-là. La compréhension se fait à froid, en le rédigeant ou en le
relisant calmement ; le runbook lui-même doit pouvoir se suivre mécaniquement, sous pression.
Un bon runbook a une structure constante : le symptôme exact qui le déclenche (le message
d'erreur précis, pas une description vague), les causes probables classées par fréquence, et
pour chacune, la commande de vérification et l'action corrective. C'est exactement la
structure d'un tableau « symptôme / cause / solution », déjà utilisée dans chaque page de ce
wiki depuis le premier module — un runbook n'est, en un sens, qu'une version de ce même tableau,
détaillée jusqu'à être exécutable sans réfléchir en plein incident.
Runbook n°1 — « Le service X ne répond plus » :
| Étape | Commande | Ce qu'on cherche |
|---|---|---|
| 1. Le conteneur tourne-t-il ? | docker ps -a \| grep X |
Statut Up ou Restarting/Exited |
| 2. Si arrêté, pourquoi ? | docker compose logs --tail 100 X |
Message d'erreur au moment de l'arrêt |
| 3. Le port attendu répond-il ? | docker exec X curl -sf localhost:<port> |
Le service répond-il depuis l'intérieur de son propre conteneur ? |
| 4. Le reverse proxy le joint-il ? | Vérifier le statut dans Uptime Kuma | Isole si le problème vient du service ou du chemin réseau vers lui |
Runbook n°2 — « Le disque est plein » :
| Étape | Commande | Ce qu'on cherche |
|---|---|---|
| 1. Confirmer et quantifier | df -h |
Quel système de fichiers, à quel pourcentage |
| 2. Identifier le plus gros consommateur | du -sh /srv/docker/* \| sort -rh \| head |
Quel service occupe le plus d'espace |
| 3. Cas fréquent : images/conteneurs obsolètes | docker system df |
Espace récupérable par Docker lui-même (images inutilisées, conteneurs arrêtés) |
| 4. Nettoyer avec prudence | docker system prune (sans -a d'abord) |
Ne jamais supprimer à l'aveugle — vérifier ce qui serait retiré avant de confirmer |
🧪 Concrètement, sur notre exemple : ce dépôt tient, depuis son tout premier incrément,
une page de synthèse des pannes rencontrées avec leur cause et leur solution — SSH,sudoà
distance, Docker, Portainer, chacune avec un symptôme exact, une cause identifiée et une
solution vérifiée. C'est, dans l'esprit, un runbook déjà en pratique : chaque nouvelle panne
réellement rencontrée y est ajoutée, plutôt que résolue une fois puis oubliée. Le piège
Docker/ufw(vu en M2 et M7)
y figure très exactement sous cette forme : symptôme, cause, solution, prêt à être réutilisé
la prochaine fois qu'il se reproduirait ailleurs.
Un runbook ne naît jamais abstrait — il se rédige après une première résolution réelle, pour ne
pas avoir à refaire tout le diagnostic la fois suivante.
# Runbook 1, étapes 1-2 combinées
docker ps -a | grep mon-service && docker compose logs --tail 100 mon-service
# Runbook 2, étapes 1-3 combinées
df -h && docker system df
Le meilleur test d'un runbook : le faire suivre par quelqu'un d'autre (ou par toi-même, quelques
semaines plus tard, sans mémoire fraîche de l'incident) et vérifier qu'il arrive à la résolution
sans avoir besoin d'aide supplémentaire.
| Symptôme | Cause probable | Solution |
|---|---|---|
| Un incident déjà résolu une fois se reproduit, et le diagnostic recommence de zéro | Résolution jamais transformée en runbook réutilisable | Écrire le runbook immédiatement après la première résolution, tant que les détails sont frais |
| Runbook trop vague pour être suivi sous pression | Rédigé comme une explication à comprendre, pas une procédure à exécuter | Structurer en étapes précises avec commandes exactes, pas en paragraphes explicatifs |
docker system prune -a exécuté sans vérification préalable |
Nettoyage à l'aveugle en situation d'urgence | Toujours vérifier ce qui serait supprimé avant de confirmer, même pendant un incident |
Parce qu'il est destiné à être suivi pendant un incident, sous pression ou fatigue — la
compréhension approfondie se fait à froid, en le rédigeant ou le relisant calmement, pas au
moment de l'urgence.
Vérifier si le conteneur tourne réellement (docker ps -a) — avant de chercher plus loin, il
faut d'abord isoler si le service a même démarré.
Parce que cette commande supprime des images et ressources potentiellement encore utiles —
vérifier ce qui serait supprimé avant de confirmer évite d'aggraver l'incident par une perte de
données ou de configuration.
Choisis un incident que tu as déjà rencontré (sur ce projet ou ailleurs) et rédige-en un runbook
complet : symptôme exact, causes probables classées par fréquence, commande de vérification et
action corrective pour chacune.
Cette formation est proposée par Deladev, studio web de Loïc D. — création de sites et d'applications, accompagnement et formation sur mesure.
Les projets réalisés · Prestations et tarifs · Le blog tech · Me contacter
Écrite par Loïc D. avec l'assistance de Claude (Anthropic) — un travail à deux.
© 2026 Deladev — publiée sous licence CC BY-NC-ND 4.0. Vous pouvez la lire, y renvoyer par un lien, la partager et la citer en créditant la source. La revendre, l'utiliser dans une prestation ou une formation payante, la republier même partiellement ailleurs, en diffuser une version modifiée ou l'exploiter pour entraîner un modèle d'IA nécessitent une autorisation écrite — pour un usage interne en entreprise, c'est souvent oui, il suffit de demander.