Débogage des conteneurs Docker : utiliser exec pour entrer dans un conteneur

L’API de l’environnement de test renvoie soudainement un 502. docker ps affiche le conteneur « Up 2 hours » — tout semble normal. Les logs ne montrent qu’un froid « Connection refused ».

C’est frustrant : le conteneur tourne, mais vous ne savez pas ce qui se passe à l’intérieur. La configuration est-elle correcte ? Les processus sont-ils démarrés ? Les ports sont-ils en écoute ? Il faut souvent « entrer » dans le conteneur pour le vérifier, comme ouvrir une boîte noire.

Au début avec Docker, je ne savais pas non plus comment « entrer » dans un conteneur. On lit docker exec, docker attach, ou « redémarrez le conteneur ». Après quelques erreurs, on comprend qu’il existe une bonne façon de déboguer.

Cet article explique comment utiliser docker exec pour diagnostiquer un conteneur : différence avec attach, outils manquants dans l’image, et astuces pratiques. Une fois maîtrisé, vous n’aurez plus besoin du seul « redémarrer et espérer ».

Bases de docker exec — entrer correctement dans un conteneur

La méthode la plus simple

Pour un conteneur en cours d’exécution :

docker exec -it my-nginx bash

Trois éléments clés :

• -it : -i garde l’entrée standard ouverte, -t alloue un terminal — vous « dialoguez » avec le conteneur
• my-nginx : nom du conteneur, ou son ID (docker exec -it abc123def456 bash)
• bash : commande à lancer dans le conteneur

Le prompt ressemble à root@abc123def456:/# : vous êtes dans le conteneur et pouvez exécuter des commandes Linux habituelles.

Si bash n’existe pas

Erreur fréquente :

$ docker exec -it my-alpine bash
OCI runtime exec failed: exec failed: container_linux.go:380:
starting container process caused: exec: "bash": executable file not found

Souvent Alpine n’inclut que sh, pas bash. Essayez :

docker exec -it my-alpine sh

En pratique : bash d’abord, sinon sh — cela couvre la plupart des cas.

Utiliser l’ID du conteneur

# Voir l'ID
$ docker ps
CONTAINER ID   IMAGE    COMMAND                  CREATED
abc123def456   nginx    "/docker-entrypoint.…"   2 hours ago

# Préfixe de 3–4 caractères suffit
$ docker exec -it abc1 bash

Docker fait correspondre le préfixe tant qu’il est unique — pratique avec beaucoup de conteneurs.

Quitter le conteneur correctement

exit ou Ctrl+D :

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

root@abc123def456:/# exit
exit
$

Avec exec, le conteneur ne s’arrête pas à la sortie. Point important pour la suite.

exec vs attach — ne plus les confondre

Différence fondamentale

Beaucoup de tutoriels citent exec et attach sans clarifier. J’ai déjà arrêté un conteneur en production en utilisant attach par erreur.

En bref :

• docker exec : lance un nouveau processus dans le conteneur (nouvelle fenêtre)
• docker attach : se connecte au processus principal (PID 1), comme un partage d’écran

Exemple : docker attach my-nginx, puis Ctrl+C ou exit — le processus principal (Nginx) reçoit le signal de fin et le conteneur s’arrête.

Avec docker exec -it my-nginx bash, bash est indépendant ; quitter bash n’affecte pas Nginx.

Quand utiliser quoi ?

Dans 99 % des cas, utilisez exec.

attach sert surtout quand vous devez interagir directement avec le processus principal :

• programme interactif (REPL Python, etc.)
• voir la sortie du processus principal en direct
• plusieurs terminaux « synchronisés » sur le même tty

Pour consulter des fichiers, modifier une config ou lancer des commandes, exec est plus sûr.

Tableau comparatif

attach vise surtout la sortie du conteneur, pas le débogage quotidien.

Outils manquants dans le conteneur

Pourquoi si peu de commandes ?

Dans le conteneur, vim ou curl peuvent manquer — frustrant au début.

C’est la philosophie des images Docker : le minimum indispensable. Ubuntu complet : centaines de Mo ; Alpine : ~5 Mo, en retirant vim, curl, ping, etc.

Installation temporaire

Selon la distribution :

Debian/Ubuntu (apt/apt-get) :

apt-get update
apt-get install -y vim curl wget net-tools
apt-get install -y iputils-ping dnsutils

CentOS/Red Hat (yum) :

yum install -y vim curl wget

Alpine (apk) :

apk update
apk add vim curl bash

Identifier la distribution

cat /etc/os-release

which apt-get   # Debian/Ubuntu
which yum      # CentOS/Red Hat
which apk      # Alpine

Souvent on tente apt-get update et on change si erreur.

Est-ce acceptable ?

Dev : installation libre ; au redémarrage le conteneur repart à zéro.

Production : uniquement en urgence pour le diagnostic ; ensuite intégrer les outils au Dockerfile.

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

Raisons : sécurité des paquets temporaires, reproductibilité (perdus au redémarrage).

Solution durable : Dockerfile

FROM nginx:latest

RUN apt-get update && apt-get install -y \
    vim \
    curl \
    wget \
    net-tools \
    iputils-ping \
 && rm -rf /var/lib/apt/lists/*

# autres configs...

rm -rf /var/lib/apt/lists/* réduit la taille de l’image.

Astuce sans vim

cat ou less suffisent souvent :

cat /etc/nginx/nginx.conf
less /etc/nginx/nginx.conf  # q pour quitter
head -n 20 /etc/nginx/nginx.conf

Modification d’urgence avec sed :

sed -i 's/listen 80/listen 8080/g' /etc/nginx/nginx.conf

Entrer avec un utilisateur spécifique

Pourquoi préciser l’utilisateur ?

root@abc123:/app# cat /var/log/app.log
cat: /var/log/app.log: Permission denied

Le conteneur peut tourner en non-root (bonne pratique en production) ; exec hérite souvent de cet utilisateur.

Entrer en root

docker exec -it --user root my-app bash
# ou
docker exec -it -u root my-app bash

UID ou nom d’utilisateur

docker exec -it --user 1000 my-app bash
docker exec -it --user appuser my-app bash
docker exec -it --user 1000:1000 my-app bash

Utile pour reproduire les problèmes de permissions :

docker exec -it --user appuser my-app bash
appuser@abc123:/app$ touch /data/test.txt
touch: cannot touch '/data/test.txt': Permission denied

Quand root est nécessaire

1. Config système sous /etc/
2. Installation de paquets (apt, yum)
3. Logs système sous /var/log/
4. chmod, chown
5. Outils réseau comme tcpdump, netstat (souvent root)

Évitez root si possible, surtout en production.

Rappel sécurité

Test : usage libre, redémarrage = reset.

Production :

• consultation → OK
• modification temporaire → à documenter
• compilation ou install dans le conteneur en cours → à éviter ; passer par le Dockerfile

Le conteneur est une infrastructure immuable : les changements runtime disparaissent au redémarrage. Le root du conteneur peut partager UID 0 avec l’hôte selon la config — d’où l’intérêt du non-root.

Astuces et scénarios courants

Une seule commande (sans shell interactif)

Sans -it :

docker exec my-nginx ls -la /etc/nginx/
docker exec my-nginx cat /etc/nginx/nginx.conf
docker exec my-nginx ps aux
docker exec my-nginx netstat -tlnp
docker exec my-nginx curl -I localhost:80

Idéal pour scripts et checks rapides :

if docker exec my-app curl -f http://localhost:8080/health; then
  echo "App is healthy"
else
  echo "App is down!"
fi

Flux de débogage standard

1. État du conteneur

docker ps -a

2. Logs

docker logs my-app --tail 100
docker logs my-app -f

3. Processus

docker exec my-app ps aux

4. Ports

docker exec my-app netstat -tlnp
docker exec my-app ss -tlnp

5. Disponibilité du service

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

docker exec my-app curl localhost:8080
docker exec my-app telnet localhost 8080

6. Configuration

docker exec my-app cat /etc/nginx/nginx.conf
docker exec my-app cat /app/config.yaml

7. Espace disque

docker exec my-app df -h

Combinaisons utiles

docker exec my-app env | grep DATABASE
docker exec my-app find /app -name "*.log"
docker exec my-app ls -la /app/
docker stats my-app

Plusieurs conteneurs

for container in $(docker ps -q); do
  echo "Container: $container"
  docker exec $container free -h
  echo "---"
done

Réseau

docker exec containerA ping containerB
docker exec my-app ping -c 3 google.com
docker exec my-app nslookup google.com

docker inspect my-app | grep IPAddress
docker exec my-app ip addr show

Conteneur qui redémarre en boucle

Méthode 1 — commande de démarrage remplacée

docker run -it --name debug-app my-app-image sh

Méthode 2 — conteneur arrêté

docker start my-app
docker logs my-app
docker exec -it my-app bash

Ces habitudes viennent du terrain ; une fois les commandes acquises, le diagnostic va plus vite.

Conclusion

L’essentiel du débogage Docker :

docker exec -it nom-conteneur bash (ou sh) est la voie la plus sûre — la sortie n’arrête pas le conteneur.

Ne confondez pas exec et attach — attach peut arrêter le conteneur à la sortie.

Outils manquants : installation temporaire (apt/yum/apk), solution durable dans le Dockerfile.

Root : --user root si besoin, avec parcimonie en production.

Ordre : logs → processus → config → réseau.

Checklist rapide :

• Conteneur en cours ? (docker ps)
• Erreurs dans les logs ? (docker logs)
• Processus actifs ? (docker exec ps aux)
• Ports en écoute ? (docker exec netstat -tlnp)
• Config correcte ? (docker exec cat config)
• Espace disque ? (docker exec df -h)
• Réseau OK ? (docker exec curl / ping)