## Introduction

Travailler avec Docker Compose peut simplifier le développement et le déploiement multi-conteneurs, mais cela introduit également son lot de pannes récurrentes. Une configuration YAML erronée, des collisions de ports, des variables manquantes ou des montages de volumes cassés peuvent empêcher une pile de démarrer, et les messages d'erreur ne sont pas toujours clairs. Ce guide transforme ces moments d'échec en un flux de travail de dépannage reproductible.

Nous allons passer en revue les erreurs Docker Compose les plus courantes, expliquer pourquoi elles surviennent et montrer des corrections étape par étape à l'aide d'exemples de commandes réelles et d'extraits de configuration. Chaque correction inclut un moyen de vérifier le résultat afin que vous puissiez avancer en toute confiance. Que vous déboguiez un environnement local ou prépariez un test de type production, les mêmes principes s'appliquent : observez d'abord l'état actuel, changez une seule chose à la fois et confirmez le comportement attendu.

Cet article s'adresse aux développeurs, aux consultants DevOps et aux équipes techniques de startups qui utilisent régulièrement Docker Compose. Il se concentre sur le diagnostic pratique et la récupération plutôt que sur une théorie générale. Vous apprendrez à interpréter les messages d'erreur de Compose, à inspecter les services sans les modifier, à persister correctement les données et à concevoir un chemin de récupération sûr lorsque quelque chose se casse.

## Inventaire de version et d'environnement

Avant de modifier toute configuration, confirmez ce qui est réellement installé et en cours d'exécution. De nombreux problèmes de « Compose » sont des incompatibilités de versions ou des conteneurs obsolètes. Commencez par des commandes en lecture seule qui affichent l'état actuel sans rien changer.

### Vérifier les versions de Docker et de Compose

La syntaxe de la commande `docker-compose` a changé entre le binaire autonome et le plugin Compose. Si vous voyez une erreur comme `docker-compose: command not found` mais que `docker compose` fonctionne, ou vice versa, vous avez probablement affaire à une incompatibilité de version ou d'installation.

Exécutez ces commandes pour voir exactement ce qui est disponible :

```bash
docker --version
# Exemple de sortie : Docker version 24.0.7, build afdd53b

docker compose version
# Exemple de sortie (plugin) : Docker Compose version v2.23.0

docker-compose --version
# Exemple de sortie (autonome) : docker-compose version 1.29.2, build 5becea4c
```

Si le binaire autonome est manquant mais que le plugin fonctionne, n'installez pas les deux et risquez une confusion. Choisissez un style d'invocation et mettez à jour tous les scripts, les Makefiles et la documentation en conséquence. Le plugin (`docker compose`) est la voie recommandée actuellement et reçoit des mises à jour continues.

### Inspecter l'état existant du projet

Un projet Compose en échec a souvent des conteneurs, des réseaux ou des volumes résiduels d'une exécution antérieure. Listez tout ce que le fichier Compose actuel gère :

```bash
docker compose ps -a
# Affiche tous les conteneurs du projet, y compris ceux arrêtés

# Exemple de sortie :
# NAME                IMAGE               COMMAND                  SERVICE   STATUS        PORTS
# myapp-web-1         myapp-web:latest    "nginx -g 'daemon of…"   web       Up 2 minutes   0.0.0.0:80->80/tcp
# myapp-db-1          postgres:15         "docker-entrypoint.s…"   db        Exited (1)     
```

Faites attention à la colonne `STATUS`. Un statut `Exited` avec un code non nul signifie que le conteneur n'a pas réussi à démarrer ou a planté. Les journaux de ce service révèlent généralement la cause.

### Lire les journaux sans rien modifier

Utilisez `docker compose logs` pour lire la sortie la plus récente d'un ou plusieurs services. Ajoutez `--tail` pour limiter le nombre de lignes et `--no-color` pour une sortie plus propre dans les scripts :

```bash
docker compose logs --tail 100 web
# Affiche les 100 dernières lignes du service web

docker compose logs -f db
# Suit les journaux du service db en temps réel (Ctrl+C pour quitter)
```

Si un conteneur est déjà en cours d'exécution mais se comporte de manière incorrecte, attachez-vous à son shell sans le reconstruire ni le redémarrer :

```bash
docker compose exec web sh
# Ouvre un shell dans le conteneur web (utilisez 'bash' si l'image le fournit)
```

Dans le shell, vous pouvez tester la connectivité réseau, vérifier les variables d'environnement et inspecter les chemins de fichiers exactement comme l'application les voit.

### Inventorier les volumes et les montages liés

La perte de données est une erreur de Compose courante mais grave. Avant de modifier ou de supprimer des conteneurs, vérifiez où chaque service écrit ses données persistantes.

```bash
docker volume ls
# Liste tous les volumes nommés

docker inspect myapp_db_data
# Remplacez par le nom de votre volume ; affiche le point de montage et d'autres métadonnées
```

Dans le fichier Compose, les volumes nommés et les montages liés ressemblent à ceci :

```yaml
version: "3.9"
services:
  db:
    image: postgres:15
    volumes:
      - db_data:/var/lib/postgresql/data  # volume nommé
      - ./backups:/backups                # montage lié

volumes:
  db_data:
```

Un volume nommé comme `db_data` est géré par Docker et survit aux reconstructions de conteneurs. Un montage lié mappe un répertoire hôte tel que `./backups` directement dans le conteneur ; il est utile pour le développement local, mais le chemin doit exister avec les bonnes permissions sur chaque machine qui exécute le fichier Compose. Si un chemin de montage lié est manquant, le conteneur peut quand même démarrer, mais les écritures iront dans la couche inscriptible du conteneur et disparaîtront à la recréation.

### Test de redémarrage pour la persistance des données

Un moyen à faible risque de vérifier que vos volumes sont configurés correctement est d'effectuer un test de redémarrage. Faites-le avant toute opération destructive :

1. Écrivez un fichier de test dans le répertoire de données du conteneur.
2. Arrêtez et recréez le conteneur.
3. Confirmez que le fichier existe toujours.

Exemple pour un service de base de données :

```bash
# Étape 1 : créer un fichier marqueur dans le répertoire de données
docker compose exec db touch /var/lib/postgresql/data/_restart_test

# Étape 2 : arrêter et recréer uniquement le service db
docker compose up -d --force-recreate db

# Étape 3 : vérifier le fichier
docker compose exec db ls /var/lib/postgresql/data/_restart_test
# Sortie attendue : /var/lib/postgresql/data/_restart_test
```

Si le fichier est manquant après la recréation, le répertoire de données n'était pas monté sur un volume persistant ou un montage lié. Ajustez le fichier Compose avant de compter sur le service pour un travail réel.

## Chemin de configuration sécurisé

Les erreurs de configuration sont la source la plus fréquente de pannes de Compose. Une petite erreur d'indentation YAML, une variable non définie ou un port déjà utilisé peut empêcher toute la pile de démarrer. Cette section passe en revue chaque problème courant et montre comment le corriger en toute sécurité.

### Valider le fichier Compose avant de l'appliquer

Exécutez toujours `docker compose config` avant `up`. Cette commande analyse et valide le fichier Compose, développe les variables d'environnement et imprime la configuration effective que Docker utiliserait. Elle détecte les erreurs de syntaxe et de nombreuses erreurs sémantiques avant la création de tout conteneur.

```bash
docker compose config
# Si le fichier est valide, il imprime le YAML normalisé.
# S'il y a une erreur, il affiche le fichier et le numéro de ligne.
```

Exemple d'une erreur YAML courante et de sa correction. Supposons que vous ayez cet extrait Compose :

```yaml
services:
  web:
    image: nginx:alpine
     ports:
      - "8080:80"
```

La clé `ports` est indentée d'un espace supplémentaire par rapport à `image`. L'exécution de `docker compose config` renvoie :

```
yaml: line 4: mapping values are not allowed in this context
```

Corrigez l'indentation pour que `ports` s'aligne avec `image`, et relancez `docker compose config` pour confirmer.

### Variables d'environnement : non définies ou mal placées

Compose prend en charge les variables d'environnement à deux endroits : la syntaxe `${VAR}` dans le fichier YAML et la section `environment` qui transmet les variables aux conteneurs. Une erreur courante consiste à référencer une variable qui n'est pas définie dans le shell ou dans un fichier `.env`.

Exemple de fichier Compose :

```yaml
services:
  api:
    image: myapp/api:${API_VERSION}
    ports:
      - "${API_PORT}:8080"
```

Si `API_VERSION` ou `API_PORT` n'est pas défini, `docker compose config` échoue avec :

```
WARN[0000] The "API_VERSION" variable is not set. Defaulting to a blank string.
```

Ou dans les versions plus récentes, `docker compose up` peut échouer entièrement. Pour corriger cela, créez un fichier `.env` dans le même répertoire que `docker-compose.yml` :

```env
API_VERSION=1.4.2
API_PORT=8080
```

Ensuite, relancez `docker compose config`. La sortie devrait maintenant montrer les valeurs substituées. Ne commitez jamais de secrets comme des mots de passe ou des clés API dans un fichier `.env` suivi par le contrôle de version ; utilisez un fichier séparé non suivi ou un gestionnaire de secrets pour les valeurs sensibles.

### Port déjà utilisé

Lorsqu'un conteneur échoue avec `port is already allocated`, cela signifie qu'un autre processus sur l'hôte (ou un autre conteneur) est déjà lié au même port. Cela arrive souvent lorsque vous exécutez plusieurs projets Compose qui mappent tous le port 80 ou 5432.

Exemple d'erreur pendant `docker compose up` :

```
Error response from daemon: driver failed programming external connectivity on endpoint myapp_web_1
Bind for 0.0.0.0:80 failed: port is already allocated
```

Pour voir ce qui utilise le port sous Linux ou macOS :

```bash
sudo lsof -i :80
# Exemple de sortie :
# COMMAND   PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
# docker-pr 1234 root    4u  IPv6  12345      0t0  TCP *:http (LISTEN)
```

Sous Windows, utilisez `netstat -ano | findstr :80` pour obtenir le PID, puis vérifiez le processus dans le Gestionnaire des tâches.

Il y a deux corrections sûres :

1. Changez le port hôte dans le fichier Compose pour un port inutilisé, par exemple `"8080:80"`.
2. Arrêtez l'autre conteneur ou processus qui utilise le port, si vous en avez le contrôle.

Relancez toujours `docker compose up -d` puis `docker compose ps` pour vérifier que le service a démarré et que les ports sont correctement mappés.

### Permission de volume refusée

Les conteneurs s'exécutent souvent en tant qu'utilisateur non root pour des raisons de sécurité, mais le répertoire de volume monté sur l'hôte peut appartenir à root ou à un autre UID/GID. Le résultat est une erreur `permission denied` lorsque le conteneur essaie d'écrire dans le volume.

Exemple de ligne de journal :

```
PermissionError: [Errno 13] Permission denied: '/app/data'
```

Pour corriger cela, vérifiez l'UID et le GID de l'utilisateur à l'intérieur du conteneur :

```bash
docker compose exec app id
# Exemple de sortie : uid=1000(appuser) gid=1000(appuser) groups=1000(appuser)
```

Ensuite, comparez avec la propriété du répertoire hôte (pour un montage lié) :

```bash
ls -ld ./data
# Exemple de sortie : drwxr-xr-x 2 root root 4096 Jun 1 10:00 ./data
```

Le répertoire hôte appartient à root, mais l'utilisateur du conteneur a l'UID 1000. Vous pouvez corriger cela de trois façons :

1. Changez la propriété du répertoire hôte pour correspondre à l'utilisateur du conteneur :
   ```bash
   sudo chown -R 1000:1000 ./data
   ```
2. Exécutez le conteneur en tant que root temporairement en définissant `user: root` dans le service Compose (uniquement pour le débogage, non recommandé pour la production).
3. Utilisez un volume nommé au lieu d'un montage lié ; Docker initialisera le volume avec les permissions correctes de l'image.

Après avoir changé la propriété, redémarrez le service et testez en créant un fichier :

```bash
docker compose exec app touch /app/data/test.txt
# Si aucune erreur, les permissions sont correctes
```

### Échecs de remplacement de commande ou de point d'entrée

Si vous remplacez la `command` ou l'`entrypoint` dans votre fichier Compose, assurez-vous que le nouvel exécutable existe dans l'image du conteneur. Une faute de frappe dans le chemin de la commande conduit à une sortie immédiate avec une erreur « not found ».

Exemple de remplacement Compose :

```yaml
services:
  web:
    image: nginx:alpine
    command: /usr/local/bin/custom-start.sh
```

Si `custom-start.sh` n'est pas présent dans l'image, le conteneur se termine avec :

```
Error: exec: "/usr/local/bin/custom-start.sh": stat /usr/local/bin/custom-start.sh: no such file or directory
```

Vérifiez que le fichier existe dans l'image sans démarrer de conteneur :

```bash
docker run --rm nginx:alpine ls -l /usr/local/bin/custom-start.sh
```

S'il est manquant, corrigez le chemin, ajoutez le script via un Dockerfile personnalisé ou utilisez une commande alternative prise en charge par l'image.

## Vérification et diagnostics

Une fois que vous avez apporté une modification, ne supposez pas que le problème est résolu. Utilisez des commandes de vérification structurées pour confirmer l'état attendu. Cette section couvre les commandes de diagnostic essentielles pour les conteneurs, les réseaux et la santé des services.

### État et santé des conteneurs

`docker compose ps` donne un aperçu rapide, mais pour une inspection plus approfondie, utilisez `docker inspect`. Il renvoie un JSON avec tous les détails d'un conteneur, y compris sa configuration, son état, ses montages et ses paramètres réseau.

```bash
docker compose ps
# État rapide

docker inspect myapp_web_1
# Sortie JSON complète
```

Pour extraire uniquement les champs dont vous avez besoin, utilisez `--format` :

```bash
docker inspect --format='{{.State.Status}}' myapp_web_1
# Exemple de sortie : running

docker inspect --format='{{.State.Health.Status}}' myapp_web_1
# Exemple de sortie : healthy (si un healthcheck est défini)
```

Si un conteneur a un healthcheck dans son Dockerfile ou son fichier Compose, le statut de santé indique si le service est réellement prêt à accepter du trafic, et non pas simplement que le processus est en cours d'exécution.

### Connectivité réseau entre les services

Compose crée un réseau par défaut pour le projet. Les services peuvent se joindre par nom de service. Si un service ne peut pas se connecter à un autre, commencez par lister les réseaux du projet :

```bash
docker network ls
# Exemple de sortie :
# NETWORK ID     NAME                DRIVER    SCOPE
# abc123def456   myapp_default       bridge    local
```

Inspectez le réseau pour voir quels conteneurs y sont attachés :

```bash
docker network inspect myapp_default
```

Ensuite, testez la résolution DNS depuis l'intérieur d'un conteneur :

```bash
docker compose exec web nslookup db
# Exemple de sortie : Address: 172.18.0.3#53, Name: db, Address 1: 172.18.0.2
```

Si le DNS échoue, assurez-vous que les deux services sont sur le même réseau et que les noms de service dans le fichier Compose correspondent à ce que l'application essaie d'atteindre. Vérifiez également les erreurs de configuration de `links` ou `depends_on`.

### Variables d'environnement dans le conteneur

Pour confirmer que les variables d'environnement sont transmises correctement, affichez-les à l'intérieur du conteneur en cours d'exécution :

```bash
docker compose exec api env | sort
# Affiche toutes les variables d'environnement dans le conteneur, triées

docker compose exec api printenv DATABASE_URL
# Affiche la valeur d'une variable spécifique
```

Si une variable est manquante ou a une mauvaise valeur, examinez les sections `environment` ou `env_file` du fichier Compose et le fichier `.env` dans le répertoire du projet.

### Vérification des journaux pour les erreurs

Les journaux sont le premier endroit à regarder pour les échecs d'exécution. Utilisez `docker compose logs` avec des noms de service et des filtres temporels :

```bash
docker compose logs --since 10m --timestamps web db
# Affiche les journaux des 10 dernières minutes pour web et db, avec horodatage
```

Si la sortie du journal est trop volumineuse, combinez `--tail` avec `--follow` de manière sélective :

```bash
docker compose logs --tail 200 -f api > api-debug.log 2>&1 &
# Écrit les 200 dernières lignes et suit le service api, en enregistrant dans un fichier
```

Lors de la lecture des journaux, recherchez des motifs d'erreur répétés, des traces de pile ou des messages de connexion refusée qui pointent vers la cause première.

## Modes de défaillance et récupération

Toutes les pannes ne sont pas des erreurs de configuration. L'épuisement du disque, les conteneurs plantés et les services orphelins peuvent également faire tomber une pile Compose. Cette section décrit comment reconnaître ces modes de défaillance et récupérer sans perdre de données ni aggraver le problème.

### Disque plein : plus d'espace sur le périphérique

Les conteneurs et les volumes peuvent remplir le disque hôte, surtout si les journaux ne sont pas rotés ou si de grands ensembles de données sont écrits dans la couche du conteneur. Un symptôme courant est une erreur comme `no space left on device` à l'intérieur d'un conteneur.

Pour vérifier l'utilisation du disque des ressources Docker :

```bash
docker system df
# Exemple de sortie :
# TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
# Images          12        3         4.2GB     2.1GB (50%)
# Containers      5         2         350MB     120MB (34%)
# Local Volumes   8         5         6.8GB     1.9GB (27%)
# Build Cache     20        0         1.1GB     1.1GB
```

Si les volumes sont en cause, listez-les par taille :

```bash
docker system df -v | sort -k7 -h
# Trie par colonne de taille
```

Pour libérer de l'espace en toute sécurité, supprimez uniquement les ressources inutilisées :

```bash
docker system prune -a --volumes
# AVERTISSEMENT : supprime tous les conteneurs, réseaux, images et volumes inutilisés.
# À utiliser avec prudence, et seulement après avoir vérifié ce qui est encore nécessaire.
```

Mieux : nettoyez les volumes inutilisés spécifiques par nom après vous être assuré qu'aucun conteneur n'en a besoin.

### Boucle de plantage de conteneur : redémarrage

Lorsqu'un conteneur affiche le statut `Restarting` et ne devient jamais sain, il est bloqué dans une boucle de plantage. La politique de redémarrage dans le fichier Compose (`restart: always` ou `unless-stopped`) continue d'essayer de redémarrer le processus, mais l'application se termine immédiatement à chaque fois.

Pour diagnostiquer, regardez le dernier code de sortie et les journaux :

```bash
docker compose ps
# Exemple de sortie :
# NAME                STATUS                          PORTS
# myapp_api_1         Restarting (1) 5 seconds ago

docker inspect --format='{{.State.ExitCode}}' myapp_api_1
# Exemple de sortie : 1

docker compose logs --tail 20 api
# Affiche l'erreur qui a causé la sortie
```

Les causes courantes incluent des fichiers de configuration manquants, de mauvaises variables d'environnement ou un conflit de port. Corrigez le problème sous-jacent, puis désactivez temporairement la politique de redémarrage pour voir l'erreur sans redémarrages répétés :

```yaml
services:
  api:
    restart: "no"
```

Après correction, réactivez la politique de redémarrage.

### Conteneurs orphelins après suppression du projet

Si vous supprimez le projet Compose avec `docker compose down`, mais que certains conteneurs restent, ce sont des « orphelins ». Cela peut arriver si vous avez utilisé `docker-compose` (autonome) pour créer le projet, puis `docker compose` (plugin) pour le gérer, ou si le nom du projet a changé.

Pour trouver les orphelins non gérés par le fichier Compose actuel, exécutez :

```bash
docker ps -a --filter "label=com.docker.compose.project"
# Liste tous les conteneurs appartenant à un projet Compose
```

Si vous voyez des conteneurs qui ne font pas partie du projet actuel, vous pouvez les supprimer individuellement après avoir confirmé qu'ils ne sont pas nécessaires :

```bash
docker rm -f <container_name_or_id>
```

Pour éviter les avertissements d'orphelins, utilisez toujours la même variante de commande Compose et le même nom de projet. Vous pouvez définir un nom de projet explicite avec `-p` ou le champ `name:` dans les versions plus récentes de Compose.

### Récupération après une mauvaise restauration de volume

Si vous restaurez un volume à partir d'une sauvegarde mais que l'application ne démarre pas en raison de problèmes de permissions ou de format, vous devez vérifier le contenu et les permissions du volume depuis un conteneur temporaire.

Exemple : un volume de base de données a été restauré, mais PostgreSQL refuse de démarrer car le répertoire de données appartient au mauvais utilisateur.

Lancez un conteneur temporaire qui monte le volume et vous permet de l'inspecter :

```bash
docker run --rm -it -v app_db_data:/data alpine sh
# À l'intérieur du conteneur :
ls -la /data
# Vérifiez la propriété et les fichiers
```

Si l'UID/GID est incorrect, vous pouvez soit faire un chown depuis l'hôte si le volume est un montage lié, soit, s'il s'agit d'un volume nommé, utiliser un conteneur temporaire avec le bon utilisateur pour corriger la propriété :

```bash
docker run --rm -v app_db_data:/data alpine chown -R 70:70 /data
# 70 est l'UID de l'utilisateur postgres dans l'image officielle
```

Ensuite, redémarrez le service de base de données et vérifiez ses journaux pour un démarrage réussi.

## Liste de contrôle des opérations

Une liste de contrôle maintient la discipline de dépannage et empêche les changements hâtifs qui aggravent les choses. Voici une liste de contrôle orientée production que vous pouvez adapter à votre équipe. Elle inclut un propriétaire nommé pour chaque élément majeur et une cadence de révision suggérée.

| Élément | Action | Vérifier | Propriétaire | Fréquence de révision |
|------|--------|--------|-------|------------------|
| 1. Environnement de référence | Enregistrez les versions de Docker et Compose, l'état actuel de la pile avec `docker compose ps -a`. | Sortie collée dans le document d'incident. | Priya Shah, responsable de l'ingénierie | Mensuelle |
| 2. Sauvegarder les volumes de données | Avant tout changement majeur, prenez un instantané ou copiez les volumes nommés. | `docker run --rm -v app_db_data:/data alpine tar czf /tmp/backup.tar.gz -C /data .` | Marcus Chen, ingénieur DevOps | Hebdomadaire pour la production |
| 3. Valider la configuration | Exécutez `docker compose config` après chaque modification du fichier Compose. | Code de sortie 0 et variables attendues développées. | Chaque développeur (auto-vérification) | Avant chaque déploiement |
| 4. Un seul changement par test | Lors du débogage, ne modifiez qu'une seule variable ou un seul paramètre à la fois. | `docker compose up -d --force-recreate <service>` réussit et le service est sain. | Développeur assigné au bogue | Par incident |
| 5. Examiner les allocations de ports | Vérifiez les conflits de ports avant de démarrer un nouveau projet. | `sudo lsof -i :<port>` ne renvoie aucun processus en conflit. | Marcus Chen, ingénieur DevOps | Lors de l'ajout d'un service |
| 6. Vérifier la persistance des données | Effectuez un test de redémarrage sur un service avec des données montées. | Le fichier marqueur existe toujours après `docker compose up -d --force-recreate`. | Priya Shah, responsable de l'ingénierie | Trimestrielle |
| 7. Surveiller l'utilisation du disque | Exécutez `docker system df` et purgez les ressources inutilisées. | Utilisation du disque inférieure à 80 % sur l'hôte. | Marcus Chen, ingénieur DevOps | Hebdomadaire |
| 8. Documenter les étapes de récupération | Tenez un runbook pour chaque erreur courante et sa correction. | Runbook accessible et testé lors d'un incident. | Priya Shah, responsable de l'ingénierie | Après chaque incident |

Cette liste de contrôle n'est pas un document statique. Revisitez-la après chaque défaillance significative ou changement de la pile. Les propriétaires listés sont des exemples ; attribuez de vrais noms dans votre équipe.

## Pièges courants et comment les éviter

Même les utilisateurs expérimentés de Compose tombent dans les mêmes pièges. Les reconnaître vous fait gagner des heures de débogage.

### Piège 1 : Utiliser `docker-compose` et `docker compose` de manière interchangeable

**Pourquoi cela arrive** : Les anciens tutoriels et la mémoire musculaire mélangent le binaire autonome et le plugin.

**Comment éviter** : Choisissez un style de commande par équipe et documentez-le. Ajoutez un script d'emballage ou un alias si nécessaire. Vérifiez les scripts et les pipelines CI pour l'ancienne syntaxe.

### Piège 2 : Coder en dur les informations d'identification dans les fichiers Compose

**Pourquoi cela arrive** : Commodité pendant le développement.

**Comment éviter** : Utilisez des variables d'environnement avec un fichier `.env` non suivi par le contrôle de version. Pour la production, utilisez les secrets Docker ou une gestion externe des secrets. Exécutez `docker compose config` pour voir si des secrets sont exposés en texte clair.

### Piège 3 : Ignorer les healthchecks

**Pourquoi cela arrive** : Les développeurs supposent qu'un conteneur est prêt lorsque le processus démarre, mais l'application peut avoir besoin de temps pour s'initialiser.

**Comment éviter** : Définissez un `healthcheck` dans le fichier Compose pour les services critiques, et utilisez `depends_on` avec `condition: service_healthy` dans les versions plus récentes de Compose. Exemple :

```yaml
services:
  db:
    image: postgres:15
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  api:
    image: myapp/api
    depends_on:
      db:
        condition: service_healthy
```

### Piège 4 : Monter des volumes avec une mauvaise propriété

**Pourquoi cela arrive** : Le répertoire hôte appartient à un utilisateur différent du processus du conteneur.

**Comment éviter** : Utilisez des volumes nommés pour les données d'application, ou définissez le bon `user:` dans le service Compose pour correspondre au propriétaire du répertoire hôte. Testez les permissions avec une simple commande d'écriture après le démarrage du conteneur.

### Piège 5 : Ne pas nettoyer les réseaux et les volumes

**Pourquoi cela arrive** : Des exécutions répétées de `docker compose up` et `down` sans `-v` laissent des ressources inutilisées qui s'accumulent.

**Comment éviter** : Utilisez `docker compose down -v` lorsque vous voulez supprimer les volumes associés (attention : cela supprime les données). Exécutez régulièrement `docker system prune` pour supprimer les réseaux inutilisés et le cache de construction.

### Piège 6 : Remplacer incorrectement le point d'entrée

**Pourquoi cela arrive** : Vous voulez exécuter un script personnalisé mais vous vous trompez dans le chemin ou oubliez que l'image de base utilise un point d'entrée spécifique.

**Comment éviter** : Testez toujours la commande avec `docker run` d'abord, et inspectez le point d'entrée par défaut de l'image avec `docker image inspect` :

```bash
docker image inspect --format='{{.Config.Entrypoint}} {{.Config.Cmd}}' nginx:alpine
# Exemple de sortie : [/docker-entrypoint.sh] [nginx -g daemon off;]
```

## Conclusion

Les erreurs courantes de Docker Compose sont rarement mystérieuses une fois que vous savez où chercher. Une approche disciplinée résoudra la plupart des problèmes en quelques minutes, pas en heures :

- Vérifiez la version et l'environnement avant de changer quoi que ce soit.
- Validez le fichier Compose et comprenez le message d'erreur exact.
- Vérifiez les ports, les variables d'environnement et les permissions de volume dans cet ordre.
- Utilisez les journaux et les commandes d'inspection pour voir la perspective du conteneur.
- Confirmez toujours la correction avec une commande de vérification et un test de redémarrage.
- Documentez les étapes de récupération afin que la prochaine personne ne répète pas la lutte.

La clé est de rendre les défaillances visibles et les changements réversibles. Commencez par une vérification à faible risque de ce guide, enregistrez l'état actuel et comparez le résultat avec la sortie attendue. Au fil du temps, vous construirez une bibliothèque mentale de symptômes et de corrections qui transforme le dépannage de Compose d'une panique en une routine.