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 :
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 :
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é :
docker inspect <nom_du_conteneur> --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 :
[{"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.
docker stop <nom_du_conteneur>
docker compose up -d
docker exec <nom_du_conteneur> 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 :
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 :
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 :
ports:
- "8080:80"
Après :
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 :
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 :
docker compose up -d
Vérifiez ensuite que le service est sain :
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 :
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
docker compose logs -f <nom_du_service>
Le drapeau -f suit les journaux en temps réel. Utilisez --tail 100 pour voir les 100 dernières lignes sans diffusion :
docker compose logs --tail 100 <nom_du_service>
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 :
docker compose exec <nom_du_service> 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 :
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 :
docker compose stop
docker compose up -d
Vérifiez ensuite le contenu de la base de données, par exemple en listant les tables :
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 :
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é avecdocker 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 configquelles variables ne sont pas résolues. - Ajoutez la variable à
.envou exportez-la dans le shell avant d'exécuterdocker compose up. - Redémarrez le service :
docker compose up -d <nom_du_service>.
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 <nom_du_service> - 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 <nom_du_service>.
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é.