Docker Compose Watch : erreurs courantes et solutions pratiques

Introduction

Docker Compose Watch est un outil puissant pour le développement local, mais lorsqu’il échoue, les erreurs peuvent être déroutantes. Vous pouvez voir des fichiers qui ne se synchronisent pas, des services qui redémarrent sans fin, ou des messages cryptiques concernant les événements, les sommes de contrôle ou les permissions. Ce guide passe en revue les erreurs les plus courantes de Docker Compose Watch, explique ce qu’elles signifient et fournit des solutions pratiques que vous pouvez appliquer immédiatement.

Nous nous concentrons sur des scénarios réels : prérequis manquants, section watch mal configurée dans compose.yaml, erreurs de chemin, conflits de volumes et particularités d’environnement. Pour chaque erreur, vous trouverez la commande exacte pour reproduire le problème, la sortie attendue et la correction avec une étape de vérification. À la fin, vous aurez une approche systématique pour déboguer les problèmes de Watch et garder votre boucle de développement rapide.

Inventaire des versions et de l’environnement

Avant de dépanner toute erreur de Watch, confirmez que votre configuration répond aux exigences minimales. Docker Compose Watch a été introduit dans Compose v2.17.0 et nécessite Docker Engine 24.0.0 ou version ultérieure. De nombreuses erreurs proviennent de versions plus anciennes.

Vérifiez vos versions de Docker et Compose :

docker --version
# Attendu : Docker version 24.0.0 ou ultérieure

docker compose version
# Attendu : Docker Compose version v2.17.0 ou ultérieure

Si votre version est plus ancienne, mettez à niveau Docker Desktop ou le moteur Docker et le plugin Compose.

Ensuite, vérifiez la structure de votre projet. docker compose watch doit être exécuté à partir d’un répertoire contenant votre compose.yaml (ou docker-compose.yaml). Vérifiez votre répertoire actuel :

pwd
# Attendu : /chemin/vers/votre/projet
ls -l compose.yaml
# Attendu : -rw-r--r-- 1 utilisateur groupe 1234 Mar 1 10:00 compose.yaml

Si le fichier est manquant, Watch ne peut pas démarrer.

Une observation rapide en lecture seule de vos conteneurs en cours d’exécution aide à identifier les conflits :

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Recherchez les conteneurs d’une exécution précédente qui pourraient détenir des verrous ou des ports.

Chemin de configuration sûr

Une section watch mal configurée est la source d’erreurs la plus courante. L’attribut watch se trouve sous un service dans compose.yaml et définit quoi synchroniser et comment réagir.

Voici une configuration minimale correcte :

services:
  web:
    image: node:18
    command: npm start
    working_dir: /app
    volumes:
      - .:/app
    watch:
      - action: sync
        path: ./src
        target: /app/src
      - action: rebuild
        path: package.json

Dans cet exemple :

• action: sync copie les modifications de ./src sur l’hôte vers /app/src dans le conteneur sans redémarrer.
• action: rebuild déclenche une reconstruction de l’image et un redémarrage du conteneur lorsque package.json change.

Erreurs de configuration courantes et leurs corrections :

1. path ou target manquant – Chaque entrée de watch a besoin des deux. Si vous omettez target, le fichier est synchronisé vers le même chemin relatif à l’intérieur du conteneur, ce qui peut ne pas être correct. Spécifiez toujours target.

1. Chemins absolus – Les chemins doivent être relatifs au répertoire du projet (où se trouve compose.yaml). Utiliser /home/user/src provoque une erreur : « path must be relative ». Correction : utilisez ./src ou src.

1. Mauvaise action – sync est destiné aux fichiers qui peuvent être rechargés à chaud (par exemple, le code source). rebuild est pour les fichiers qui nécessitent une nouvelle image (par exemple, les dépendances). sync+restart redémarre le conteneur après la synchronisation, utile pour les fichiers de configuration. Choisissez la bonne action pour éviter des reconstructions inutiles ou des mises à jour manquées.

1. Ignorer les fichiers ignorés – Par défaut, Watch respecte .dockerignore et .gitignore. Si un fichier y est répertorié, il ne sera pas surveillé. Pour passer outre, ajoutez ignore: false à l’entrée watch :

watch:
  - action: sync
    path: ./dist
    target: /app/dist
    ignore: false

1. Conflits de volumes – Si un chemin target de watch est également défini comme volume bind mount dans la section volumes, la sémantique peut entrer en conflit. Watch gère son propre montage. Évitez les montages bind dupliqués pour les répertoires surveillés.

Après avoir modifié compose.yaml, redémarrez Watch :

docker compose watch

Vous devriez voir une sortie comme :

[+] Running 1/0
 ✔ Container myproject-web-1  Created
[+] Watching for changes...

Vérification et diagnostics

Lorsque Watch est en cours d’exécution mais que les fichiers ne se synchronisent pas, vérifiez directement le mécanisme de synchronisation.

Tout d’abord, vérifiez si le processus Watch est actif :

docker compose ls --filter name=myproject
# Attendu : NAME                STATUS              CONFIG FILES
#          myproject           running(1)          /chemin/compose.yaml

Si le statut du projet est exited, démarrez-le avec docker compose up -d puis docker compose watch.

Pour tester la synchronisation, créez un fichier dans le répertoire surveillé :

echo "console.log('hello');" > src/test.js

Inspectez ensuite le fichier du conteneur :

docker compose exec web ls -l /app/src/test.js
# Attendu : -rw-r--r-- 1 root root 24 Mar 1 10:05 /app/src/test.js

Si le fichier est manquant ou a un contenu obsolète, la synchronisation a échoué.

Consultez les journaux du conteneur pour les événements Watch :

docker compose logs web --tail 20

Recherchez des lignes comme :

web-1  | [watch] file changed: /app/src/test.js
web-1  | [watch] syncing file to container...

Si vous voyez « permission denied », c’est un problème de permission de fichier. Assurez-vous que l’utilisateur dans le conteneur a un accès en écriture au répertoire cible. Vous pouvez spécifier user dans le service :

services:
  web:
    image: node:18
    user: "1000:1000"  # correspond à l'utilisateur hôte
    # ...

Pour des diagnostics plus approfondis, exécutez Watch en mode verbeux :

docker compose --verbose watch

Cela affiche des informations de débogage sur la surveillance des fichiers et la gestion des événements.

Modes de défaillance et récupération

Voici des modes de défaillance spécifiques et comment s’en remettre.

Erreur : « watch is not a valid attribute »

Cela apparaît lors de l’utilisation d’une ancienne version de Compose. Vérifiez docker compose version. Mettez à niveau vers v2.17.0+.

Erreur : « path must be relative »

Vous avez utilisé un chemin absolu dans watch. Passez à un chemin relatif comme ./src.

Erreur : « unable to prepare context: path not found »

Le path dans une action rebuild n’existe pas. Assurez-vous que le fichier existe dans le répertoire du projet.

Erreur : « cannot watch a directory outside the project root »

Watch ne peut surveiller que les fichiers à l’intérieur du répertoire du projet (ou de ses sous-répertoires). Déplacez les fichiers dans le projet ou utilisez un bind mount sans watch.

Erreur : « file does not exist » lors de l’utilisation de sync+restart

Le fichier cible doit exister dans le conteneur avant la synchronisation. Créez-le manuellement ou incluez-le dans l’image.

La synchronisation fonctionne mais l’application ne se recharge pas

Certains frameworks nécessitent un observateur de fichiers à l’intérieur du conteneur. Assurez-vous que votre serveur de développement fonctionne avec le rechargement à chaud. Par exemple, Node avec nodemon, Python avec uvicorn --reload, ou React avec react-scripts start.

Watch s’arrête après une reconstruction

Lorsqu’une action rebuild se déclenche, le processus Watch peut redémarrer. S’il se termine, exécutez à nouveau docker compose watch. Pour éviter des reconstructions répétées, envisagez d’utiliser sync+restart pour les fichiers de configuration qui ne nécessitent pas une nouvelle image.

Erreurs de permission de fichier

Si le conteneur s’exécute en tant que root mais que vos fichiers hôtes appartiennent à un autre utilisateur, la synchronisation peut échouer avec « permission denied ». Définissez l’option user dans le service pour correspondre à votre ID utilisateur hôte, ou ajustez les permissions du répertoire.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle avant et pendant le dépannage de Watch pour rester systématique.

• [ ] Vérification de version : Exécutez docker compose version et confirmez v2.17.0+. Si plus ancienne, mettez à niveau.
• [ ] Répertoire du projet : Exécutez pwd et ls compose.yaml pour vous assurer d’être au bon endroit.
• [ ] Validation de configuration : Exécutez docker compose config pour valider la syntaxe YAML. Corrigez toute erreur.
• [ ] Statut des conteneurs : Exécutez docker compose ps pour voir si les services sont en marche. Sinon, docker compose up -d.
• [ ] Démarrage de Watch : Exécutez docker compose watch. Notez toute erreur de démarrage.
• [ ] Test de synchronisation : Créez ou modifiez un fichier dans un répertoire surveillé, puis vérifiez à l’intérieur du conteneur avec docker compose exec <service> ls -l <cible>.
• [ ] Inspection des journaux : Exécutez docker compose logs <service> --tail 50 pour voir les événements watch et les journaux d’application.
• [ ] Correction de permission : Si permission refusée, ajoutez user à la définition du service et redémarrez.
• [ ] Résolution de chemin : Assurez-vous que tous les chemins watch sont relatifs et à l’intérieur de la racine du projet.
• [ ] Règles d’ignorance : Vérifiez .dockerignore et .gitignore pour les exclusions involontaires. Utilisez ignore: false si nécessaire.

Pièges courants et comment les éviter

Plusieurs erreurs récurrentes font trébucher les développeurs utilisant Compose Watch. Voici comment les reconnaître et les éviter.

Piège 1 : Supposer que Watch reconstruit l’image à chaque changement de fichier

Beaucoup d’utilisateurs s’attendent à ce que watch reconstruise l’image pour chaque changement, ce qui conduit à une itération lente. En réalité, l’action sync ne fait que copier des fichiers. Si vous avez besoin d’une reconstruction, utilisez action: rebuild et spécifiez les fichiers exacts (comme package.json) pour éviter des reconstructions inutiles.

Piège 2 : Ne pas définir correctement target

Si le répertoire de travail de votre conteneur est /app et que votre source est dans ./src, vous pourriez écrire target: /src au lieu de /app/src. Le fichier se retrouve dans le mauvais répertoire et l’application ne le voit pas. Vérifiez toujours la structure des répertoires du conteneur avec docker compose exec <service> pwd et ls.

Piège 3 : Oublier de redémarrer Watch après avoir modifié compose.yaml

Les modifications de la configuration watch nécessitent de redémarrer docker compose watch. Le processus en cours ne recharge pas automatiquement sa propre configuration. Arrêtez-le avec Ctrl+C et relancez-le.

Piège 4 : Utiliser des bind mounts pour le même répertoire que watch

Si vous avez un bind mount comme .:/app et que vous définissez également watch avec sync vers /app/src, vous pouvez obtenir un comportement inattendu car le bind mount écrase les fichiers synchronisés. Supprimez le bind mount pour le sous-répertoire surveillé et laissez Watch le gérer.

Piège 5 : Ignorer les incompatibilités de permissions de fichiers

Les conteneurs s’exécutent souvent en tant que root, mais votre utilisateur hôte peut ne pas être root. Les fichiers synchronisés peuvent se retrouver avec une mauvaise propriété. Définissez user: "${UID}:${GID}" dans le service pour correspondre à votre utilisateur hôte.

Éviter ces pièges vous fera gagner du temps et de la frustration.

Conclusion

Docker Compose Watch est un outil précieux pour le rechargement à chaud du code en développement, mais il nécessite une configuration correcte et une compréhension de ses actions. Ce guide a couvert les exigences de version, la syntaxe de configuration, les commandes de diagnostic, les modes de défaillance courants et une liste de contrôle pratique. En suivant les étapes, vous pouvez résoudre rapidement les erreurs de Watch et maintenir un flux de développement fluide.

Comme prochaines étapes, expérimentez avec différentes actions (sync, rebuild, sync+restart) pour voir laquelle convient à votre projet. Ensuite, intégrez docker compose watch dans votre routine de développement quotidienne et surveillez les journaux pour tout comportement inattendu. N’oubliez pas que la clé d’un dépannage efficace est d’observer avant de changer, de faire un changement à la fois et de vérifier le résultat.