Intro
Les conteneurs en production sont faciles à démarrer, mais bien plus difficiles à exploiter de manière cohérente. Un guide de débogage utile montre quoi configurer, quelle commande prouve que la configuration fonctionne, et à quoi ressemble l’échec lorsque la configuration est erronée.
Ce guide couvre les commandes de débogage Docker que les développeurs utilisent le plus souvent : logs, exec, inspect, stats, ainsi que des vérifications pratiques pour les conteneurs qui échouent ou se comportent de façon inattendue. L’objectif est pratique — comprendre les éléments mobiles, les tester localement et éviter les surprises lorsque les mêmes patterns passent en CI/CD ou en production.
Workflow Overview
Un débogage Docker efficace suit une boucle simple : identifier la ressource, apporter un seul changement de configuration, puis exécuter la commande qui prouve que l’état observé correspond aux attentes. Documenter ce qui casse lorsque la configuration est absente, mal configurée ou exécutée dans un environnement proche de la production.
Les équipes découvrent souvent des hypothèses cachées à cette étape. Les chemins locaux, les tags d’image, les noms de réseau, les fichiers d’environnement, les limites de ressources et les permissions se comportent différemment sur les portables, les runners CI et les hôtes de production. Rendre ces hypothèses explicites avant de s’appuyer sur la configuration.
Commandes de base pour le workflow de débogage :
| Commande | Objectif | Cas d’utilisation typique |
|---|---|---|
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"" | Lister les conteneurs en cours avec statut et ports | Inventaire rapide de ce qui tourne |
docker logs <conteneur> --tail 100 | Afficher les dernières lignes de log | Repérer les échecs de démarrage ou erreurs d’exécution |
docker inspect <conteneur> | Métadonnées complètes du conteneur (montages, réseaux, env, healthcheck) | Vérifier les montages de volumes, la config réseau, le statut du healthcheck |
docker stats <conteneur> --no-stream | CPU, mémoire, réseau, I/O bloc actuels | Confirmer que les limites de ressources sont appliquées |
Pour les projets Compose, les équivalents sont docker compose ps, docker compose logs -f <service> et docker compose exec <service> sh — ils permettent de déboguer sans reconstruire l’image.
Hypothèses de stockage à vérifier
Avant de modifier les conteneurs, confirmez où les fichiers sont réellement stockés. Un volume nommé comme app_data:/var/lib/app est géré par Docker et survit aux reconstructions de conteneur proprement. Un bind mount comme ./data:/var/lib/app mappe directement un répertoire hôte — utile en développement local, mais il introduit des problèmes de permissions, de portabilité et de sauvegarde si le même chemin n’existe pas sur une autre machine.
Effectuez un test de redémarrage : arrêtez le conteneur, recréez-le, et vérifiez que l’application voit toujours les fichiers attendus. Si les données disparaissent, le service écrivait dans le système de fichiers du conteneur au lieu d’un volume ou d’un mount.
Local Pilot Plan
Un pilote local valide le workflow de débogage contre une charge de travail réaliste avant de s’engager dans l’automatisation ou la promotion. Choisissez un service représentatif et faites-le passer par un cycle complet : build, run, inspect, stress, stop, recréer.
Pilot étape par étape
- Build avec un tag fixe —
docker build -t myapp:v1.2.3 .évite l’ambiguïté du taglatestqui cause les échecs « ça marche sur ma machine ». - Run avec limites explicites —
docker run -d --name pilot --memory=512m --cpus=1.0 -p 8080:80 myapp:v1.2.3rend les contraintes de ressources visibles àdocker stats. - Vérifier health et montages —
docker inspect pilot | jq '.[0].Mounts, .[0].State.Health'confirme que les volumes sont montés et que les healthchecks passent. - Simuler la charge —
hey -z 30s -c 10 http://localhost:8080/(ouab,wrk) génère du trafic pendant que vous exécutezdocker stats pilot --no-streamtoutes les 10 secondes. Surveillez la croissance mémoire ou le throttling CPU. - Consulter les logs sous charge —
docker logs pilot --tail 50 --since 30srévèle erreurs de timeout, épuisement de pool de connexions ou pauses GC qui n’apparaissent pas à l’inactivité. - Redémarrer et valider la persistance —
docker stop pilot && docker rm pilot, puis relancez l’étape 2. Interrogez l’application (oudocker exec pilot ls -la /var/lib/app) pour confirmer que les données ont survécu.
Ce que le pilote expose
- Healthchecks manquants : le conteneur affiche « healthy » mais l’application renvoie des 500.
- Mauvaise configuration de volume : le bind mount fonctionne localement mais échoue en CI car le chemin hôte n’existe pas.
- Limites de ressources trop strictes : OOM kills sous charge modeste ;
docker inspectmontreOOMKilled: true. - Problèmes de driver de logs : le driver JSON-file remplit le disque ;
docker logstronque la sortie.
Documentez chaque découverte avec la commande exacte qui l’a révélée. Cela devient le runbook de débogage de votre équipe pour ce service.
Conclusion
Le débogage de conteneurs Docker fonctionne mieux lorsque l’équipe traite la configuration comme quelque chose à tester, pas seulement à copier. Gardez les exemples simples, exécutez les commandes localement et confirmez le comportement attendu avant d’ajouter des services ou de l’automatisation.
Pour une prochaine étape, choisissez un service et documentez les commandes exactes pour le build, le run, l’inspect, le stop et le recréer. Comparez les résultats aux exigences de production — rétention des logs, survie des données persistantes, quotas de ressources — afin que l’implémentation s’intègre au modèle d’exploitation global.
Un workflow de conteneur fiable rend l’échec visible : les logs sont faciles à trouver, les données persistantes survivent aux reconstructions de conteneurs, et le comportement local correspond assez à la production pour attraper les erreurs tôt.