## Introduction Passer d'une pile Docker Compose d'un ordinateur portable à la production échoue souvent parce que l'environnement local ne ressemble pas assez à la production. Un laboratoire local contrôlé comble cette lacune. Ce guide détaille comment construire un environnement Docker Compose semblable à la production sur une seule machine, avec des commandes pratiques, des sorties attendues et des étapes de reprise pour les pannes courantes. Le lecteur visé est un développeur, un consultant DevOps ou un membre d'une équipe technique de démarrage qui comprend déjà les concepts de base de Docker, mais qui a besoin d'un processus reproductible pour déployer et exploiter des services basés sur Compose en toute sécurité. L'accent est mis sur la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des variables d'environnement au lieu de secrets, vérifier chaque résultat et documenter comment récupérer si l'état attendu n'est pas atteint. À la fin de cet article, vous disposerez d'un laboratoire local réutilisable qui comprend la vérification des versions et de l'environnement, un chemin de configuration sûr, la vérification et le diagnostic, les modes de défaillance avec reprise et une liste de contrôle opérationnelle. Chaque section inclut des commandes que vous pouvez exécuter immédiatement et la sortie attendue. ## Inventaire des versions et de l'environnement Avant de modifier quoi que ce soit, capturez l'état actuel de Docker et du projet Compose. Cela évite les modifications accidentelles et fournit une base de référence pour le dépannage. ### 1. Enregistrer les versions de Docker et Compose Exécutez : ```bash docker --version docker compose version ``` Exemple de sortie attendue : ``` Docker version 24.0.7, build afdd53b Docker Compose version v2.23.0 ``` Notez ces versions. Les commandes Compose v2 utilisent `docker compose` (avec un espace), tandis que l'ancienne version v1 utilise `docker-compose` (avec un trait d'union). De nombreux tutoriels montrent encore l'ancienne syntaxe ; utiliser la bonne pour votre environnement évite les erreurs « command not found ». ### 2. Lister les conteneurs et services en cours d'exécution Vérifiez ce qui est actuellement en cours d'exécution : ```bash docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" ``` Exemple de sortie attendue : ``` NAMES STATUS PORTS web Up 10 minutes 0.0.0.0:8080->80/tcp db Up 10 minutes 3306/tcp ``` Si un conteneur est manquant ou redémarre, c'est un signal pour inspecter les journaux avant de faire des modifications. ### 3. Inspecter un conteneur sans le modifier Utilisez `docker inspect` pour voir les montages, les réseaux, les variables d'environnement et l'état de santé : ```bash docker inspect --format '{{json .Mounts}}' ``` Cette commande est en lecture seule et sûre. Par exemple, elle indiquera si le conteneur utilise un volume nommé ou un montage bind : ```json [{"Type":"volume","Name":"myapp_data","Source":"/var/lib/docker/volumes/myapp_data/_data","Destination":"/var/lib/app"}] ``` ### 4. Vérifier la persistance des données Un test local semblable à la production doit inclure un test de redémarrage. Arrêtez le conteneur, recréez-le et confirmez que l'application voit toujours les fichiers attendus. ```bash docker stop docker compose up -d docker exec ls /var/lib/app ``` Si le répertoire est vide après la recréation, le service écrivait dans le système de fichiers du conteneur au lieu d'un volume ou d'un montage. Corrigez cela avant de continuer. **Piège courant :** Utiliser un montage bind avec un chemin relatif qui diffère selon les machines. Pour un laboratoire portable, préférez les volumes nommés pour les données applicatives et réservez les montages bind pour le code source ou les fichiers de configuration que vous modifiez localement. ## Chemin de configuration sûr Les modifications de configuration doivent être délibérées et réversibles. Cette section fournit une approche étape par étape pour modifier un fichier Compose en toute sécurité dans un laboratoire local. ### 1. Sauvegarder le fichier Compose actuel Faites toujours une copie horodatée avant de modifier : ```bash cp docker-compose.yml docker-compose.yml.bak.$(date +%Y%m%d) ``` Cela permet un retour en arrière instantané si un changement cause des problèmes. ### 2. Utiliser des variables d'environnement pour les secrets Ne codez jamais en dur des mots de passe ou des clés API dans le fichier Compose. À la place, référencez des variables d'environnement : ```yaml services: db: image: postgres:16 environment: POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} ``` Créez ensuite un fichier `.env` (et ajoutez-le à `.gitignore`) : ``` POSTGRES_PASSWORD=change-me-in-production ``` Pour les laboratoires locaux, utilisez des valeurs fictives qui ne sont manifestement pas des secrets de production. Cela évite une exposition accidentelle si le laboratoire est partagé. ### 3. Modifier un élément à la fois Si vous devez changer à la fois un mappage de port et un volume, faites-les séparément et testez après chaque changement. Cela isole la cause en cas de problème. Exemple : changez le port du service web de 8080 à 8081. Avant : ```yaml ports: - "8080:80" ``` Après : ```yaml ports: - "8081:80" ``` Exécutez `docker compose up -d` et vérifiez avec `curl localhost:8081`. ### 4. Valider la syntaxe du fichier Compose Exécutez toujours : ```bash docker compose config ``` Cela analyse le fichier et signale toute erreur de syntaxe ou variable manquante. Cela développe également les variables d'environnement pour que vous puissiez voir la configuration finale rendue sans rien démarrer. La sortie attendue en cas de succès est la configuration YAML complète avec les variables substituées. En cas d'erreur, elle affichera un message tel que : ``` ERROR: The Compose file './docker-compose.yml' is invalid because: services.db.environment.POSTGRES_PASSWORD contains {"POSTGRES_PASSWORD": null}, which is an invalid type, it should be a string ``` ### 5. Appliquer et vérifier Après modification, appliquez le changement : ```bash docker compose up -d ``` Vérifiez ensuite que le service est sain : ```bash docker compose ps ``` La sortie attendue montre le service comme `running` ou `healthy` si un healthcheck est défini. **Piège courant :** Oublier de définir la variable d'environnement. Si `docker compose config` montre `POSTGRES_PASSWORD: null` ou une chaîne vide, la variable est manquante dans le shell ou le fichier `.env`. ## Vérification et diagnostic Cette section explique comment confirmer que la pile fonctionne comme prévu et comment diagnostiquer les problèmes lorsque ce n'est pas le cas. ### 1. Vérifier l'état et la santé des conteneurs Exécutez : ```bash docker compose ps ``` Exemple de sortie : ``` NAME COMMAND SERVICE STATUS PORTS myapp-web-1 "nginx -g 'daemon of…" web running 0.0.0.0:8080->80/tcp myapp-db-1 "docker-entrypoint.s…" db running (healthy) 5432/tcp ``` Un service avec `(unhealthy)` signifie que le healthcheck échoue. Inspectez les journaux de ce service. ### 2. Lire les journaux récents ```bash docker compose logs -f ``` Le drapeau `-f` suit les journaux en temps réel. Utilisez `--tail 100` pour voir les 100 dernières lignes sans diffusion : ```bash docker compose logs --tail 100 ``` Recherchez les lignes d'erreur telles que connexion refusée, fichiers manquants ou permission refusée. ### 3. Exécuter des commandes dans un conteneur en cours d'exécution Pour déboguer sans modifier l'image : ```bash docker compose exec sh ``` À l'intérieur du conteneur, vous pouvez vérifier la connectivité réseau, les permissions de fichiers et les variables d'environnement. Par exemple, pour tester la connectivité du service web vers la base de données : ```bash nc -zv db 5432 ``` Sortie attendue si joignable : ``` Connection to db 5432 port [tcp/postgresql] succeeded! ``` ### 4. Vérifier à nouveau la persistance des données Après que le service a fonctionné pendant un certain temps, arrêtez-le et redémarrez-le pour confirmer que les données survivent : ```bash docker compose stop docker compose up -d ``` Vérifiez ensuite le contenu de la base de données, par exemple en listant les tables : ```bash docker compose exec db psql -U postgres -c "\dt" ``` Si les tables sont manquantes, le volume n'a pas été monté correctement. **Piège courant :** Se fier au nom de réseau par défaut. Les conteneurs sur le même réseau Compose peuvent se joindre par nom de service, mais seulement s'ils sont dans le même projet. Si vous voyez des erreurs de résolution DNS, vérifiez que les deux services sont définis dans le même `docker-compose.yml` et que vous n'avez pas créé accidentellement des réseaux séparés. ## Modes de défaillance et reprise Les laboratoires de type production doivent inclure des scénarios de défaillance réalistes. Voici des modes de défaillance courants et comment récupérer de chacun. ### Défaillance 1 : Port déjà utilisé Symptôme : ``` Error response from daemon: driver failed programming external connectivity on endpoint myapp_web_1: Bind for 0.0.0.0:8080 failed: port is already allocated ``` Pourquoi cela arrive : Un autre processus sur l'hôte, ou un autre conteneur, écoute déjà sur le même port. Reprise : - Identifiez le processus utilisant le port : `sudo lsof -i :8080` - Soit arrêtez ce processus, soit changez le port hôte dans le fichier Compose. - Par exemple, changez `"8080:80"` en `"8081:80"` et redémarrez : `docker compose up -d`. ### Défaillance 2 : Le volume de base de données ne persiste pas les données Symptôme : Après `docker compose down` et `up`, la base de données est vide. Pourquoi cela arrive : Le service de base de données écrit dans le système de fichiers du conteneur par défaut. Sans volume nommé, ces données sont perdues lorsque le conteneur est recréé. Reprise : - Ajoutez un volume nommé à la définition du service : ```yaml services: db: image: postgres:16 volumes: - db_data:/var/lib/postgresql/data volumes: db_data: ``` - Ensuite, exécutez à nouveau `docker compose up -d`. Le volume persiste jusqu'à ce qu'il soit explicitement supprimé avec `docker volume rm`. ### Défaillance 3 : Variable d'environnement manquante Symptôme : Le service se termine immédiatement ou les journaux montrent une variable nulle. Pourquoi cela arrive : La variable requise n'est pas définie dans le shell ou dans le fichier `.env`. Reprise : - Vérifiez avec `docker compose config` quelles variables ne sont pas résolues. - Ajoutez la variable à `.env` ou exportez-la dans le shell avant d'exécuter `docker compose up`. - Redémarrez le service : `docker compose up -d `. ### Défaillance 4 : Le conteneur redémarre en boucle Symptôme : `docker compose ps` montre `Restarting` au lieu de `Up`. Pourquoi cela arrive : L'application à l'intérieur du conteneur plante au démarrage, souvent en raison d'une mauvaise configuration. Reprise : - Vérifiez les journaux : `docker compose logs ` - Causes courantes : identifiants de base de données incorrects, montage manquant ou erreur de syntaxe dans un fichier de configuration. - Corrigez le problème sous-jacent, puis redémarrez : `docker compose restart `. ### Défaillance 5 : Le healthcheck marque incorrectement le service comme non sain Symptôme : Le service est `running` mais signalé `unhealthy`. Pourquoi cela arrive : La commande de healthcheck peut être incorrecte, ou elle peut nécessiter des outils absents de l'image. Reprise : - Inspectez la définition du healthcheck dans le fichier Compose. - Exécutez la commande healthcheck manuellement dans le conteneur pour voir sa sortie. - Ajustez les paramètres du healthcheck (intervalle, délai d'attente, tentatives) ou corrigez la commande. - Redémarrez le service et attendez que l'état de santé se mette à jour. ## Liste de contrôle opérationnelle Utilisez cette liste de contrôle avant et après avoir apporté des modifications au laboratoire. Attribuez un responsable unique à chaque élément pour garantir la responsabilisation, et examinez-la au moins une fois par semaine pendant le développement actif. | Vérification | Commande / Action | Résultat attendu | Responsable | Fréquence | |-------|------------------|-----------------|-------|-----------| | Versions Docker cohérentes | `docker --version && docker compose version` | La sortie correspond aux versions documentées dans le runbook de l'équipe | Priya Shah, responsable DevOps | Hebdomadaire | | Tous les services en cours d'exécution | `docker compose ps` | Chaque service affiche `Up` ou `healthy` | Priya Shah | À chaque changement | | Pas de journaux d'erreurs récents | `docker compose logs --tail 50` | Aucune erreur fatale ou exception répétée | Alex Chen, développeur backend | Quotidien | | Persistance des données vérifiée | `docker compose down && docker compose up -d && docker compose exec db psql -c "\dt"` | Les tables existent toujours après le redémarrage | Alex Chen | Hebdomadaire | | Ports non exposés de manière inattendue | `docker compose ps --format '{{.Ports}}'` | Seuls les ports prévus sont publiés | Priya Shah | À chaque changement | | Pas de secrets dans le fichier Compose | `grep -i password docker-compose.yml` | Aucun secret codé en dur ; seulement des références `${VAR}` | Revue de sécurité (Lee Wong) | Mensuel | | Sauvegarde des volumes existante | `docker run --rm -v myapp_data:/data -v $(pwd):/backup alpine tar czf /backup/data.tgz /data` | Le fichier de sauvegarde est créé et non vide | Lee Wong | Hebdomadaire | | Utilisation des ressources dans les limites | `docker stats --no-stream` | CPU < 80 %, mémoire < 1 Go pour le laboratoire | Priya Shah | Hebdomadaire | | Procédure de reprise documentée | Examiner la section `Recovery.md` du runbook | Les étapes sont à jour et testées | Priya Shah | Mensuel | **Remarque :** Remplacez les noms des responsables par les membres réels de l'équipe. Les fréquences de révision peuvent être ajustées en fonction du risque du projet. ## Conclusion Un laboratoire local de déploiement de production Docker Compose n'a de valeur que si vous le traitez comme de la production. Cela signifie délimiter les versions, observer en lecture seule d'abord, un changement à la fois et vérifier après chaque étape. Les commandes et vérifications de cet article fournissent un cadre de départ. Commencez par une vérification à faible risque : exécutez `docker compose ps`, confirmez que tous les services sont sains, puis effectuez un test de redémarrage pour valider la persistance des données. À partir de là, ajoutez progressivement des scénarios plus complexes à votre laboratoire, tels que des partitions réseau ou des contraintes de ressources. L'objectif est de rendre les défaillances visibles tôt, de protéger les valeurs sensibles et de définir les étapes de reprise avant qu'un incident ne se produise. Un flux de travail technique fiable ne fait pas que prévenir les problèmes ; il vous donne la confiance que lorsque quelque chose casse, vous pouvez le réparer rapidement et en toute sécurité.