Comment déboguer des conteneurs Docker sur Debian 13

Introduction

Dans ce tutoriel, vous apprendrez à déboguer des conteneurs Docker en utilisant des techniques pratiques et adaptées aux débutants. Vous identifierez les problèmes en vérifiant le statut des conteneurs, en analysant les journaux, en inspectant la configuration et en accédant à l'environnement du conteneur. Cette approche vous aide à comprendre rapidement pourquoi un conteneur échoue et comment le réparer.

Objectif final : À la fin de ce tutoriel, vous serez capable d'identifier et de résoudre les problèmes courants des conteneurs Docker en utilisant les journaux, l'inspection et les outils d'analyse en temps réel.

Prérequis

• Public cible : Administrateurs système débutants
• Temps estimé : ~30 minutes
• Système d'exploitation : Debian 13
• Logiciel : Docker 24.0 ou version ultérieure
• Permissions : Utilisateur avec privilèges sudo ou membre du groupe docker
• Exigences matérielles : Au moins 2 Go de RAM et 10 Go d'espace disque libre
• Exigences réseau : Accès Internet pour télécharger des images, aucun port spécifique requis pour ce tutoriel
• Exigences : Utilisation basique de la ligne de commande et un service Docker en cours d'exécution
• Compatibilité : Testé sur Debian 13 et fonctionne sur Debian 12 et Ubuntu 22.04

Étape 1 : Vérifier les informations système de Docker

Avant de déboguer un conteneur spécifique, vérifiez que Docker lui-même fonctionne correctement.
Exécutez la commande suivante :

docker system info

Vous verrez des informations détaillées sur l'environnement Docker, y compris :

• Version du serveur
• Pilote de stockage
• Nombre de conteneurs et d'images
• Disponibilité du CPU et de la mémoire
• Répertoire racine de Docker

Cela vous aide à confirmer que :

• Docker fonctionne correctement
• Le système dispose de suffisamment de ressources
• Il n'y a pas de problèmes de configuration globale

Pour vérifier le statut du service Docker :

systemctl status docker

Vous verrez si le service Docker est actif. S'il ne fonctionne pas, démarrez-le :

sudo systemctl start docker

Vous devriez maintenant voir le service en état actif.

Étape 2 : Vérifier le statut du conteneur

Exécutez la commande suivante :

docker ps

Vous verrez une liste des conteneurs en cours d'exécution avec des détails tels que l'ID du conteneur, l'image et le statut. Si votre conteneur apparaît avec le statut "Up", il est actuellement en cours d'exécution.

Pour inclure les conteneurs arrêtés :

docker ps -a

Vous verrez maintenant tous les conteneurs. Si votre conteneur affiche "Exited", cela signifie qu'il s'est arrêté en raison d'une erreur ou a terminé son exécution.

Étape 3 : Voir les journaux du conteneur

Les journaux montrent ce que l'application à l'intérieur du conteneur produit. C'est l'étape la plus importante pour le débogage. Vous pouvez obtenir <CONTAINER_ID> via la commande docker ps décrite à l'étape 2.

Exécutez :

docker logs <CONTAINER_ID>

Vous verrez la sortie de l'application, y compris les erreurs et les avertissements. Recherchez les messages indiquant des échecs tels que des fichiers manquants ou des erreurs de connexion.

Pour suivre les journaux en temps réel :

docker logs -f <CONTAINER_ID>

Vous verrez de nouvelles entrées de journal au fur et à mesure qu'elles apparaissent. Cela est utile lors du redémarrage d'un conteneur et de l'observation du comportement.

Pour voir uniquement les journaux récents :

docker logs --tail 50 <CONTAINER_ID>

Vous verrez les 50 dernières lignes de sortie. Cela vous aide à vous concentrer sur les événements les plus récents.

Étape 4 : Inspecter l'état du conteneur

Docker stocke des informations détaillées sur chaque conteneur.

Exécutez :

docker inspect <CONTAINER_ID>

Vous verrez une sortie JSON structurée avec des détails de configuration et d'exécution.

Pour vérifier le statut du conteneur :

docker inspect -f '{{.State.Status}}' <CONTAINER_ID>

Vous verrez une valeur simple telle que "running" ou "exited", ce qui confirme l'état du conteneur.

Pour vérifier le code de sortie :

docker inspect -f '{{.State.ExitCode}}' <CONTAINER_ID>

Vous verrez un nombre. Une valeur de 0 signifie succès, tandis que toute valeur non nulle indique une erreur.

Pour vérifier la politique de redémarrage :

docker inspect -f '{{.HostConfig.RestartPolicy.Name}}' <CONTAINER_ID>

Vous verrez si le conteneur est configuré pour redémarrer automatiquement.

Codes de sortie courants que vous pouvez voir :

• 0 – Le processus s'est terminé avec succès sans erreurs. Cela signifie généralement que le conteneur s'est arrêté normalement. Par exemple, un script a terminé sa tâche et s'est arrêté.
• 1 – Une erreur générale s'est produite. C'est le code d'échec le plus courant et signifie généralement que quelque chose à l'intérieur de l'application a échoué, comme un fichier manquant, une configuration invalide ou une erreur d'exécution.
• 125 – Docker n'a pas pu exécuter le conteneur. Cela indique généralement un problème avec la commande docker run elle-même, comme des options invalides ou des paramètres incorrects.
• 126 – La commande à l'intérieur du conteneur ne peut pas être exécutée. Cela signifie souvent des problèmes de permission ou que le fichier n'est pas exécutable.
• 127 – La commande n'a pas été trouvée. Cela signifie généralement que le binaire ou le script spécifié n'existe pas à l'intérieur du conteneur.
• 137 – Le conteneur a été arrêté de force. Cela se produit souvent lorsque le système manque de mémoire et tue le processus du conteneur.
• 139 – Le conteneur s'est écrasé avec une faute de segmentation. Cela indique une erreur d'application sérieuse, souvent liée à des problèmes d'accès à la mémoire.
• 143 – Le conteneur a été arrêté gracieusement. Cela se produit généralement lorsque vous exécutez docker stop et que le conteneur s'arrête correctement.

Étape 5 : Accéder à l'environnement du conteneur

Parfois, les journaux ne suffisent pas. Vous pouvez entrer dans le conteneur pour l'inspecter directement.

Exécutez :

docker exec -it <CONTAINER_ID> /bin/bash

Vous entrez dans un shell interactif à l'intérieur du conteneur.

Si bash n'est pas disponible :

docker exec -it <CONTAINER_ID> /bin/sh

Vous pouvez maintenant explorer le conteneur.

Vérifiez les processus du conteneur en cours d'exécution depuis l'hôte :

docker top <CONTAINER_ID>

Vous verrez les processus actifs à l'intérieur du conteneur. Si le processus principal manque, le conteneur peut s'arrêter.

Étape 6 : Surveiller l'utilisation des ressources

Les conteneurs peuvent échouer en raison de ressources limitées.

Exécutez :

docker stats

Vous verrez l'utilisation en temps réel du CPU, de la mémoire et du réseau pour tous les conteneurs.

Pour surveiller un conteneur spécifique :

docker stats <CONTAINER_ID>

Vous verrez un tableau en direct qui se met à jour en continu avec l'utilisation des ressources pour tous les conteneurs en cours d'exécution. Chaque ligne représente un conteneur, et chaque colonne montre un type spécifique d'utilisation des ressources.
Les colonnes les plus importantes sont :

• CPU % – Montre combien de CPU le conteneur utilise. Des valeurs élevées peuvent indiquer un traitement intensif ou un code inefficace.
• MEM USAGE / LIMIT – Montre combien de mémoire le conteneur utilise par rapport à sa limite. Si l'utilisation est proche de la limite, le conteneur peut ralentir ou être arrêté.
• MEM % – Pourcentage de mémoire utilisée par rapport à la limite.
• NET I/O – Trafic réseau. Cela montre combien de données le conteneur a reçues et envoyées. Des valeurs élevées peuvent indiquer une activité réseau intense.
• BLOCK I/O – Activité de lecture et d'écriture sur disque. Cette colonne montre combien de données le conteneur a lues et écrites sur le disque.
• PIDs – Nombre de processus en cours d'exécution à l'intérieur du conteneur. Un nombre très élevé peut indiquer une fuite de processus ou une application incontrôlée.

Étape 7 : Vérifier les événements Docker

Docker enregistre des événements qui décrivent ce qui se passe au niveau du système et des conteneurs. Ces événements vous aident à comprendre quand un conteneur démarre, s'arrête, plante ou redémarre.
Exécutez la commande suivante :

docker events

Vous verrez un flux en direct d'événements tels que le démarrage, l'arrêt et le redémarrage des conteneurs. La sortie se met à jour en continu en temps réel.

Filtrer les événements pour un conteneur spécifique

Exécutez :

docker events --filter container=<CONTAINER_ID>

Vous verrez uniquement les événements liés au conteneur sélectionné. Cela vous aide à vous concentrer sur une seule charge de travail.

Afficher les événements d'une plage de temps spécifique

Pour voir les événements à partir d'un moment spécifique :

docker events --since 10m

Vous verrez les événements des 10 dernières minutes.

Pour définir à la fois l'heure de début et de fin :

docker events --since 2026-01-01T10:00:00 --until 2026-01-01T11:00:00

Vous verrez les événements qui se sont produits dans cette plage de temps.

Formater la sortie des événements

Exécutez :

docker events --format '{{.Time}} {{.Type}} {{.Action}} {{.Actor.ID}}'

Vous verrez une sortie formatée avec les champs sélectionnés. Cela facilite la lecture ou l'intégration avec des scripts.

Filtrer des types d'événements spécifiques

Vous pouvez filtrer les événements pour vous concentrer sur des problèmes spécifiques.

Arrêts ou plantages de conteneurs

Exécutez :

docker events --filter event=die

Vous verrez les événements lorsque les conteneurs s'arrêtent. Cela aide à identifier les arrêts inattendus.

Événements de manque de mémoire

Exécutez :

docker events --filter event=oom

Vous verrez les événements lorsqu'un conteneur est tué en raison de limites de mémoire. C'est crucial pour diagnostiquer les problèmes de ressources.

Redémarrages de conteneurs

Exécutez :

docker events --filter event=restart

Vous verrez quand les conteneurs redémarrent. Des événements de redémarrage fréquents peuvent indiquer une boucle de plantage.

Combiner les filtres et la plage de temps

Exécutez :

docker events --since 10m --filter event=die

Vous verrez les événements d'arrêt de conteneur des 10 dernières minutes. Cela aide à restreindre les échecs récents.

Étape 8 : Vérifier l'utilisation du disque et nettoyer les images inutilisées

Docker stocke les images, les conteneurs, les volumes et le cache sur le disque. Au fil du temps, les données inutilisées peuvent consommer un espace important et causer des problèmes.

Exécutez la commande suivante :

docker system df

Vous verrez un résumé de l'utilisation du disque, y compris :

• Images
• Conteneurs
• Volumes locaux
• Cache de construction

Chaque section montre :

• Nombre total
• Éléments actifs
• Taille
• Espace récupérable

Cela vous aide à comprendre combien d'espace disque Docker utilise et combien peut être nettoyé.

Pour voir les images inutilisées, exécutez :

docker images -f dangling=true

Vous verrez les images qui ne sont pas étiquetées et non utilisées par un conteneur. Ce sont des candidats sûrs pour la suppression.

Pour supprimer les images inutilisées, exécutez :

docker image prune

Vous serez invité à confirmer. Après confirmation, les images inutilisées sont supprimées et l'espace disque est libéré.

Pour supprimer toutes les images inutilisées, pas seulement celles en attente :

docker image prune -a

Vous supprimez toutes les images qui ne sont utilisées par aucun conteneur.

Vérification et tests

• Exécutez docker ps et confirmez que le statut du conteneur est correct.
• Exécutez docker logs et vérifiez que les erreurs sont identifiées ou résolues.
• Exécutez docker inspect et confirmez que le statut et le code de sortie correspondent aux attentes.
• Utilisez docker exec pour confirmer que les processus s'exécutent à l'intérieur du conteneur.
• Si le débogage est réussi, le conteneur devrait rester en état de fonctionnement sans erreurs critiques dans les journaux.

Annulation des modifications

Si vous avez apporté des modifications lors du débogage, vous pouvez restaurer un état propre.

Arrêtez un conteneur :

docker stop <CONTAINER_ID>

Vous verrez la confirmation que le conteneur a été arrêté.

Supprimez un conteneur :

docker rm <CONTAINER_ID>

Vous verrez la confirmation que le conteneur a été supprimé.

Recréez le conteneur :

docker run <OPTIONS> <IMAGE_NAME>

Un nouveau conteneur est créé à partir de l'image.

Dépannage

Le conteneur se termine immédiatement

Vérifiez docker logs pour les messages d'erreur. Ceux-ci expliquent généralement le problème.

Impossible d'accéder au conteneur

Assurez-vous qu'il est en cours d'exécution en utilisant docker ps.

Aucun journal disponible

Assurez-vous que l'application écrit la sortie sur stdout ou stderr.

Le conteneur redémarre de manière répétée

Vérifiez la politique de redémarrage et les journaux pour identifier les boucles de plantage.

Utilisation élevée des ressources

Utilisez docker stats pour confirmer les pics de CPU ou de mémoire.

Conclusion

Vous avez appris à déboguer des conteneurs Docker en vérifiant leur statut, en analysant les journaux, en inspectant la configuration et en accédant à l'environnement du conteneur. Ces techniques vous permettent d'identifier et de résoudre rapidement les problèmes courants. Comme prochaine étape, explorez le débogage de Docker Compose et les systèmes de journalisation centralisée pour gérer plusieurs conteneurs.