Docker Compose Watch : concepts avancés et exemples pratiques

Introduction

Docker Compose Watch est un outil de surveillance et de synchronisation de fichiers qui aide les développeurs à construire et tester des applications conteneurisées plus rapidement en mettant à jour automatiquement les services en cours d'exécution lorsque les fichiers sources changent. Il comble le fossé entre les reconstructions complètes lentes et les copies manuelles de fichiers, permettant le rechargement à chaud pour les langages interprétés et une synchronisation rapide pour les ressources statiques.

Cet article explique les concepts avancés de Docker Compose Watch, notamment son architecture, ses modes de configuration, l'inventaire de l'environnement, les chemins de configuration sûrs, le diagnostic, les modes de défaillance et les listes de vérification opérationnelles. Il s'adresse aux développeurs, aux praticiens DevOps et aux équipes techniques de startups qui comprennent déjà Docker Compose de base et souhaitent utiliser Watch de manière fiable dans des environnements de type production. Chaque section comprend des commandes concrètes, les sorties attendues et les étapes de récupération.

L'objectif est la sécurité opérationnelle : observer avant de changer, limiter le rayon d'action, utiliser des variables d'environnement plutôt que des secrets, vérifier les résultats et documenter les plans de retour en arrière.

Fonctionnement de Docker Compose Watch

Docker Compose Watch utilise un modèle client-serveur. La commande docker compose watch s'exécute sur l'hôte, surveille les événements de fichiers dans le répertoire du projet et communique avec un serveur Watch intégré au démon Docker ou à un conteneur auxiliaire. Le serveur Watch applique ensuite les actions aux services cibles.

Watch prend en charge trois actions de configuration dans la section x-watch ou watch d'un fichier Compose :

Sync : Copie les fichiers modifiés de l'hôte vers un conteneur en cours d'exécution sans le recréer. Idéal pour le code source dans les langages interprétés comme Python, Node.js ou PHP.
Rebuild : Reconstruit l'image du conteneur et recrée le service. Nécessaire pour les changements qui affectent la construction de l'image, tels que le Dockerfile, les dépendances ou le code compilé.
Sync+restart : Copie les fichiers puis redémarre le processus du conteneur, utile lorsqu'une application a besoin d'un redémarrage pour prendre en compte les changements mais ne nécessite pas une reconstruction complète de l'image.

Un compose.yaml minimal avec Watch pourrait ressembler à ceci :

services:
  web:
    image: node:20-alpine
    working_dir: /app
    command: node server.js
    volumes:
      - .:/app
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: rebuild
          path: package.json

La section develop.watch définit les actions. Dans cet exemple, les modifications sous ./src sont synchronisées directement vers le répertoire /app/src du conteneur, tandis que les modifications de package.json déclenchent une reconstruction de l'image car les dépendances peuvent avoir changé.

Inventaire des versions et de l'environnement

Avant d'utiliser Watch, confirmez vos versions de Docker et de Compose. Docker Compose Watch est disponible dans Docker Desktop 4.19 et versions ultérieures, et dans la CLI Compose v2.17.0 et supérieure. Vérifiez avec :

docker compose version
# Sortie attendue : Docker Compose version v2.27.0

Vérifiez également que le démon Docker prend en charge Watch. Le serveur Watch est intégré au moteur Docker sur Docker Desktop, mais sur Linux, vous devrez peut-être activer le magasin d'images containerd. Utilisez docker info et recherchez CDI spec directories ou Server Version pour vérifier.

Prérequis essentiels

Docker Engine 23.0 ou version ultérieure.
Docker Compose v2.17.0 ou version ultérieure.
Fichiers du projet montés ou accessibles au processus Watch.
Pour les actions de synchronisation, le conteneur doit avoir un accès en écriture au chemin cible.
Pour les actions de reconstruction, le service doit pouvoir être construit à partir du fichier Compose.

Observation de l'état actuel

Exécutez ces commandes en lecture seule pour capturer les informations de base :

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
# Exemple de sortie :
# NAMES        STATUS          PORTS
# web_1        Up 2 minutes    0.0.0.0:8000->8000/tcp
# db_1         Up 2 minutes    5432/tcp

docker compose ps
# Affiche l'état des services, les codes de sortie et la santé

docker compose logs --tail 50 web
# Les 50 dernières lignes de journal du service web

Stockage des données et volumes

Watch ne gère pas la persistance des données ; il synchronise uniquement les fichiers. Confirmez où votre application stocke son état avant de compter sur le rechargement à chaud.

Volume nommé : app_data:/var/lib/app est géré par Docker, survit à la recréation du conteneur. À utiliser pour des données de type production.
Montage bind : ./data:/var/lib/app mappe directement un répertoire hôte. Utile pour le développement, mais peut causer des problèmes de permissions et de portabilité.

Testez la persistance avec un redémarrage :

docker compose stop web
docker compose up -d web
docker compose exec web ls /var/lib/app

Si les fichiers sont absents, le service écrivait dans le système de fichiers éphémère du conteneur au lieu d'un volume ou d'un montage bind.

Chemin de configuration sûr

Configurer Watch en toute sécurité signifie changer une action à la fois et vérifier son effet avant de l'étendre.

Flux de travail recommandé

Commencez avec un seul service et une seule action sync.
Placez des fichiers de test minimaux dans le répertoire surveillé.
Observez le flux de journaux pour confirmer les événements.
Ajoutez progressivement d'autres chemins et actions.
Introduisez ensuite seulement les déclencheurs rebuild pour les fichiers critiques de l'image.

Exemple : Ajout de la synchronisation à un service Node.js

Supposons que votre fichier Compose ait un service web défini par un Dockerfile. Pour activer le rechargement à chaud des changements de source sans reconstruire l'image, ajoutez :

services:
  web:
    build: .
    ports:
      - "3000:3000"
    develop:
      watch:
        - action: sync
          path: ./src
          target: /usr/src/app/src
        - action: rebuild
          path: package.json

Démarrez Watch :

docker compose watch
# Sortie :
# watching [./src]
# watching [package.json]
# Press Ctrl+C to stop

Apportez une modification à src/server.js, puis vérifiez les journaux :

docker compose logs -f web
# Ligne de journal attendue : File changed: ./src/server.js, syncing to /usr/src/app/src/server.js

Le service ne redémarrera pas, l'application doit donc détecter les changements de fichiers (par exemple, node --watch ou une bibliothèque de surveillance de fichiers) pour que le nouveau code prenne effet. Si l'application ne se recharge pas automatiquement, envisagez d'utiliser sync+restart :

        - action: sync+restart
          path: ./src
          target: /usr/src/app/src

Secrets et variables d'environnement

Ne codez jamais en dur des secrets dans les fichiers Compose qui sont surveillés ou synchronisés. Utilisez la substitution de variables d'environnement avec un fichier .env (exclu de la synchronisation) ou les secrets Docker.

Exemple :

services:
  web:
    environment:
      - DATABASE_URL=${DATABASE_URL}

Gardez .env dans .gitignore et ne l'incluez dans aucun chemin sync.

Contrôle du rayon d'action

Utilisez des chemins spécifiques dans les champs path plutôt que la racine du projet.
Pour les monorepos, divisez les chemins Watch par service pour éviter des reconstructions inutiles.
Testez la configuration Watch dans un projet Compose de staging avant de l'appliquer à la production.

Vérification et diagnostic

Après avoir configuré Watch, vérifiez que chaque action se comporte comme prévu.

Vérification de la synchronisation

Créez un fichier de test dans le répertoire surveillé :

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

Vérifiez le système de fichiers du conteneur :

docker compose exec web cat /usr/src/app/src/test.js
# Attendu : voir le même contenu

Confirmez que l'horodatage du fichier correspond au fichier hôte.

Vérification de la reconstruction

Modifiez package.json en ajoutant un commentaire de dépendance inoffensif.
Observez la sortie du journal Watch :

Rebuilding web...
[+] Building 2.1s (12/12) FINISHED

Confirmez que le conteneur a été recréé :

docker ps --filter "name=web" --filter "status=running"
# Vérifiez que l'horodatage STARTED est récent

Commandes de diagnostic

docker compose events affiche les événements de cycle de vie, y compris la recréation du conteneur.
docker inspect web montre les points de montage, les variables d'environnement et l'état de santé.
docker compose logs --tail 100 web pour la sortie de l'application.
docker top web pour voir les processus en cours d'exécution dans le conteneur.

Si la synchronisation ne se produit pas, vérifiez que le chemin dans la configuration watch est relatif au fichier Compose et que le conteneur est en cours d'exécution.

Modes de défaillance et récupération

Pannes courantes avec Watch et comment les résoudre.

1. La cible de synchronisation n'existe pas

Symptôme : Les journaux Watch affichent une erreur comme path /usr/src/app/nonexistent does not exist in container.

Cause : Le chemin target est absent de l'image du conteneur ou du volume.

Récupération : Assurez-vous que le répertoire est créé dans le Dockerfile ou via un script de point d'entrée. Exemple d'ajout au Dockerfile :

RUN mkdir -p /usr/src/app/src

2. Boucle de reconstruction ou reconstructions excessives

Symptôme : Watch reconstruit continuellement le service même sans modification de fichiers.

Cause : Un fichier surveillé est modifié par le processus de construction lui-même, créant une boucle de rétroaction.

Récupération : Évitez de surveiller les fichiers que la construction ou l'application modifie. Utilisez un fichier d'ignorance ou réduisez le chemin de synchronisation. Par exemple, si la construction génère un fichier dans src/, excluez-le avec un .dockerignore ou ajustez le path vers un sous-répertoire.

3. Erreurs de permission lors de la synchronisation

Symptôme : Watch signale permission denied lors de la copie de fichiers.

Cause : L'utilisateur du conteneur n'a pas la permission d'écriture sur le répertoire cible.

Récupération : Assurez-vous que l'utilisateur du conteneur possède le chemin cible. Dans le Dockerfile :

RUN chown -R node:node /usr/src/app
USER node

Ou exécutez le conteneur en tant que root pendant le développement (non recommandé pour la production).

4. Watch ne détecte pas les changements sur macOS

Symptôme : Les fichiers modifiés sur l'hôte ne sont pas détectés.

Cause : Limites des événements du système de fichiers ou permissions sur macOS.

Récupération : Augmentez le nombre maximal de surveillants de fichiers ou redémarrez Docker Desktop. Alternativement, utilisez le polling (si pris en charge) ou passez à un montage bind avec délégation complète.

5. Redémarrage du conteneur au lieu de la synchronisation

Symptôme : Un changement d'un fichier configuré pour la synchronisation provoque le redémarrage du conteneur.

Cause : L'action est accidentellement définie sur sync+restart ou rebuild, ou le processus de l'application est supervisé par une politique de redémarrage.

Récupération : Vérifiez l'action dans compose.yaml. Passez à sync si un redémarrage n'est pas nécessaire. Vérifiez la politique de redémarrage du service :

restart: "no"

Question rapide 2 sur 2

Dans l'exemple Node.js de l'article, à quoi s'applique la règle 'ignore' sous une action de synchronisation ?

L'article indique : « la règle ignore s'appliquerait à myproject/web/node_modules/, et non à myproject/node_modules/ ».

Pièges courants

Évitez ces erreurs lors de l'utilisation de Docker Compose Watch.

Chemins de synchronisation trop larges

Erreur : Synchroniser ./ vers /app sans exclusions.

Pourquoi : Copie node_modules, .git et les secrets, provoquant des synchronisations lentes et des fuites de données potentielles.

Correction : Synchronisez uniquement les répertoires nécessaires et utilisez .dockerignore pour exclure les motifs.

S'appuyer sur Watch pour les déploiements en production

Erreur : Exécuter docker compose watch sur des serveurs de production.

Pourquoi : Watch est conçu pour le développement ; il ajoute une surcharge et peut perturber les services involontairement.

Correction : Utilisez docker compose up -d pour la production et les pipelines CI/CD pour les mises à jour.

Ignorer les conflits de propriété de fichiers

Erreur : Synchroniser des fichiers en tant que root lorsque l'application s'exécute en tant qu'utilisateur non root.

Pourquoi : L'application ne peut pas modifier les fichiers, entraînant des erreurs d'exécution.

Correction : Exécutez Watch en tant que même utilisateur ou ajustez les permissions avant la synchronisation.

Ne pas tester les déclencheurs de reconstruction

Erreur : Supposer que les déclencheurs de reconstruction fonctionnent sans test.

Pourquoi : Un Dockerfile manquant ou une dépendance de construction peut provoquer des échecs de reconstruction à un moment inopportun.

Correction : Déclenchez manuellement une reconstruction dans un environnement de staging et vérifiez que l'image se construit.

Liste de vérification opérationnelle

Liste de vérification de préparation opérationnelle pour l'utilisation de Docker Compose Watch en équipe ou en environnement de staging. Chaque élément comprend un responsable et une fréquence de révision.

Élément de vérification	Détails	Responsable	Fréquence de révision
Compatibilité des versions	Vérifier Docker Engine >= 23.0, Compose >= v2.17.0	Lead DevOps (ex. : Priya Shah)	Mensuelle
Audit de la configuration Watch	S'assurer que les cibles de synchronisation existent et que les chemins sont étroits	Développeur lead d'équipe (ex. : Carlos Mendez)	Hebdomadaire pendant le développement actif
Analyse des secrets	Confirmer qu'aucun secret n'est dans les chemins de synchronisation ou les fichiers Compose	Ingénieur sécurité (ex. : Aisha Khan)	Bi-hebdomadaire
Test de performance	Mesurer la latence de synchronisation et l'utilisation des ressources	Ingénieur performance (ex. : Tom Okafor)	Mensuelle avant la sortie
Exercice de défaillance	Simuler un échec de synchronisation et une boucle de reconstruction ; vérifier les procédures de récupération	Ingénieur d'astreinte (rotation)	Trimestrielle
Mise à jour de la documentation	Mettre à jour le guide de dépannage Watch avec les nouveaux problèmes	Rédacteur technique (ex. : Lena Fischer)	Après tout incident

Chaque responsable est chargé d'exécuter la vérification et de mettre à jour la fréquence en fonction des défaillances observées.

Conclusion

Docker Compose Watch est un outil puissant pour accélérer les flux de travail de développement, mais il nécessite une configuration et une surveillance minutieuses pour éviter les pièges. En comprenant son architecture, en utilisant un chemin de configuration sûr, en vérifiant les actions avec des commandes concrètes et en planifiant la récupération, les équipes peuvent intégrer Watch dans leurs pratiques quotidiennes en toute confiance.

Commencez par une action de synchronisation petite et à faible risque sur un service de développement, capturez l'état de base et étendez progressivement. Révisez régulièrement la liste de vérification opérationnelle et maintenez la documentation à jour. Avec ces pratiques, Docker Compose Watch devient un composant fiable de votre boîte à outils de développement de conteneurs.

Comme prochaine étape, choisissez un service dans votre projet Compose actuel, ajoutez une section develop.watch avec un chemin de synchronisation étroit, exécutez docker compose watch et observez les journaux pour voir la synchronisation de fichiers en temps réel en action.