Docker Compose : aide-mémoire pour serveurs

Les commandes Compose que vous utilisez réellement

Docker Compose fournit plus de quarante sous-commandes. L’administration quotidienne d’un serveur en utilise environ une douzaine. Cette page les regroupe selon la tâche à effectuer, donne une raison simple pour chacune et renvoie vers l’explication détaillée lorsqu’une commande présente un piège.

Tout ce qui suit utilise Compose V2 : docker compose avec un espace, et non l’ancien script docker-compose. V2 est un plugin Go qui s’installe avec Docker Engine. V1 ne figure plus dans les paquets actuels. Ainsi, l’absence de docker-compose: command not found sur une nouvelle installation Ubuntu en juillet 2026 est normale et n’indique pas une panne. Vérifiez avec docker compose version. Si cette commande n’affiche rien, installez le paquet docker-compose-plugin.

Toutes les commandes ci-dessous s’exécutent depuis le répertoire qui contient votre compose.yaml, car Compose détermine le nom du projet à partir de ce répertoire et recherche le fichier relativement à celui-ci. Si vous exécutez la même commande un niveau plus haut, Compose s’arrête avec no configuration file provided: not found. Si le format du fichier vous est encore inconnu, commencez par un premier fichier Compose sur un VPS, puis revenez ici pour les commandes.

Cycle de vie : les quatre commandes que vous saisissez et celle qui supprime les conteneurs

docker compose up -d
docker compose up -d --wait
docker compose stop
docker compose start
docker compose restart web
docker compose down

up -d crée le réseau, crée les conteneurs, les démarre, puis se termine. La commande se termine dès que les conteneurs sont créés. C’est pourquoi un script de déploiement qui exécute ensuite une sonde curl échoue souvent au premier essai. up -d --wait attend que chaque service qui déclare un healthcheck indique l’état healthy, puis retourne un code différent de zéro si l’un d’eux n’atteint jamais cet état. Le comportement de cette option dépend entièrement du contrôle utilisé. Rédigez donc un healthcheck fiable pour Compose avant de l’utiliser dans une automatisation.

stop arrête les conteneurs et les conserve. start redémarre donc les mêmes conteneurs avec la même couche inscriptible. down les arrête, puis supprime les conteneurs et le réseau du projet. Tout ce qui est écrit dans le conteneur, mais en dehors d’un volume, est supprimé avec eux. C’est la confusion la plus coûteuse dans Compose. La différence complète entre down et stop explique dans quels cas ce comportement pose problème.

restart n’est pas un reload. La commande arrête et redémarre le même conteneur avec la configuration qu’il possède déjà. Une variable d’environnement modifiée, un nouveau tag d’image ou une nouvelle configuration de port n’a donc aucun effet. Pour appliquer une modification du fichier, exécutez de nouveau up -d. Compose compare chaque service à son conteneur en cours d’exécution et recrée uniquement ceux dont la configuration a changé.

Appliquer une modification : recréer, récupérer ou reconstruire

docker compose up -d --force-recreate
docker compose pull && docker compose up -d
docker compose build --no-cache web
docker compose up -d --build web

up -d ne fait rien si aucune modification n'est détectée, ce qui permet de l'exécuter plusieurs fois sans risque. --force-recreate ignore cette comparaison et remplace chaque conteneur, même lorsque la configuration est identique. C'est donc le moyen le plus rapide de supprimer un état anormal dans un conteneur.

La mise à jour d'une image nécessite 2 commandes, car elles ont des fonctions différentes. pull télécharge l'image actuelle pour chaque tag indiqué dans le fichier. up -d constate ensuite que l'ID de l'image du service ne correspond plus à celui de son conteneur en cours d'exécution et recrée ce conteneur. Si vous omettez le pull, up -d continue d'exécuter l'ancien latest du mois dernier sans signaler d'erreur.

build s'applique aux services qui déclarent une section build: au lieu d'une section image:. up -d --build construit et démarre le service en une seule étape. C'est la boucle normale lorsque vous modifiez du code. Utilisez --no-cache uniquement lorsqu'une couche mise en cache est manifestement obsolète, car cette commande reconstruit chaque couche depuis zéro.

Voir ce qui est en cours d’exécution

docker compose ps
docker compose ps -a
docker compose logs -f --tail=100
docker compose logs --since 15m --timestamps db
docker compose top
docker compose ls

ps liste uniquement les conteneurs en cours d’exécution. Un service qui s’est arrêté pendant son démarrage n’y apparaît pas tant que vous n’ajoutez pas -a. Un conteneur absent de ps alors que ps -a l’affiche avec l’état Exited (1) correspond donc normalement à un échec du démarrage. Consultez le code de sortie, puis les logs.

logs -f suit tous les services simultanément et préfixe chaque ligne avec le nom du service. C’est la vue à utiliser lorsque les services communiquent entre eux et que l’ordre des événements est important. Indiquez un service pour limiter l’affichage. --tail=100 est utile pour un conteneur actif depuis un mois, car l’affichage par défaut imprime tout l’historique et surcharge le terminal. --since 15m répond généralement à votre question : que s’est-il passé pendant le redémarrage que vous venez d’effectuer ?

top liste les processus présents dans chaque conteneur. Cela permet de distinguer « le conteneur est en cours d’exécution » de « le processus qu’il contient est en cours d’exécution ». ls sort du répertoire actuel et liste tous les projets Compose présents sur l’hôte avec leur état. Vous pouvez ainsi retrouver la stack démarrée il y a trois mois.

Ouvrir un shell dans un service

docker compose exec web sh
docker compose exec -u root web sh
docker compose run --rm web env
docker compose run --rm --no-deps web sh

exec exécute une commande dans un conteneur déjà démarré. run démarre un nouveau conteneur à partir de la même définition de service. Vous devez l'utiliser lorsque le service ne reste pas démarré assez longtemps pour pouvoir utiliser exec. Associez toujours run à --rm. Sinon, chaque exécution laisse un conteneur arrêté, et ceux-ci s'accumulent jusqu'à rendre docker compose ps -a illisible.

Essayez sh avant bash. Les images basées sur Alpine ne contiennent pas bash, et l'échec affiche exec: "bash": executable file not found in $PATH. L'ajout de --no-deps à run ignore les dépendances du service. Cela évite qu'une vérification rapide de la configuration ne démarre toute votre base de données.

run --rm web env est le moyen le plus rapide de voir l'environnement réellement attribué à un service, après la fusion de chaque fichier .env, bloc environment: et variable de shell. Lorsqu'une valeur est incorrecte, l'ordre de fusion en est généralement la cause. la manière dont Compose résout les fichiers env et les secrets indique quelle source est prioritaire.

Réseaux, ports et résolution de noms

docker compose port web 80
docker compose exec web getent hosts db
docker compose config --networks

Compose place tous les services sur un réseau de projet unique. Le nom de chaque service est un nom DNS sur ce réseau. L’exécution de getent hosts db dans web affiche l’adresse IP du conteneur lorsque la résolution fonctionne, et n’affiche rien dans le cas contraire. Vous pouvez ainsi vérifier en deux secondes si « ces conteneurs peuvent communiquer ». Si le nom est résolu, mais que la connexion est refusée, le processus dans db est lié à 127.0.0.1 au lieu de 0.0.0.0. Il n’accepte donc aucun paquet provenant d’un autre conteneur. Le reste de ce modèle est expliqué dans le fonctionnement des réseaux Compose et du DNS des services.

port web 80 affiche l’adresse de l’hôte et le port sur lequel le port d’un conteneur est publié. Vous n’avez ainsi pas à deviner la valeur lorsque le mapping provient d’une variable. La publication d’un port crée également une règle de pare-feu que Docker gère lui-même. Cette règle est prioritaire sur les vôtres. Un service que vous pensiez privé peut donc être accessible depuis Internet. Ce cas est expliqué dans pourquoi les ports Docker publiés contournent ufw.

Volumes et données

docker compose config --volumes
docker compose cp db:/etc/postgresql/pg_hba.conf ./pg_hba.conf
docker compose down -v

config --volumes affiche les volumes nommés déclarés par le projet, un par ligne. Cette liste correspond aux données à sauvegarder. cp copie un fichier vers ou depuis un conteneur sans ouvrir de shell, en utilisant la forme service:path du côté où se trouve le conteneur.

down -v supprime ces volumes nommés avec les conteneurs. Cette commande convient pour supprimer une stack de test. Elle ne convient pas aux éléments contenant des données importantes, car elle ne demande aucune confirmation et il est impossible d’annuler l’opération. Les bind mounts y survivent, car ils résident dans le système de fichiers de l’hôte. Cette différence de portée des dommages est l’une des raisons pour lesquelles il faut choisir délibérément entre les bind mounts et les volumes nommés.

Nettoyage qui libère de l’espace disque sans perte de données

docker compose down --remove-orphans
docker system df
docker image prune -a
docker builder prune

--remove-orphans supprime les conteneurs appartenant au projet mais qui n’apparaissent plus dans le fichier. C’est exactement ce qui se produit après le renommage d’un service. Sans cette option, ces conteneurs continuent de s’exécuter et restent invisibles pour docker compose ps.

docker system df indique où l’espace disque est utilisé avant toute suppression. La commande distingue les images, les conteneurs, les volumes locaux et le cache de build, avec une valeur récupérable pour chacun. image prune -a supprime toutes les images vers lesquelles aucun tag ne pointe. Sur un serveur ayant téléchargé plusieurs versions d’une image volumineuse, c’est généralement le nettoyage le plus efficace. builder prune vide le cache de build, qui augmente progressivement sur tout serveur qui construit ses propres images.

Aucune de ces commandes ne modifie un volume nommé. Seuls docker volume prune et docker compose down -v le font.

Vérifier le fichier avant qu’il ne provoque un problème

docker compose config --quiet
docker compose config --services
docker compose --dry-run up -d

config --quiet valide le fichier et n’affiche rien en cas de réussite. Il convient donc à une étape de pre-deploy ou à un git hook. config sans option affiche le fichier entièrement fusionné et interpolé. Cela permet de vérifier qu’une variable a bien été résolue et qu’un fichier de remplacement a été appliqué comme prévu. Une variable non définie apparaît alors avec une valeur vide, à côté de l’avertissement The "X" variable is not set. Defaulting to a blank string.

--dry-run est une option globale, et non une option de sous-commande. Elle doit donc être placée avant up. Cette option affiche toutes les actions que Compose effectuerait sans rien modifier. Ces trente secondes sont bien investies avant un down sur une stack importante.

Travailler avec plusieurs fichiers, profils et projets

docker compose -f compose.yaml -f compose.prod.yaml up -d
docker compose --profile debug up -d
docker compose -p staging up -d

Plusieurs options -f sont fusionnées dans l’ordre, et les fichiers suivants remplacent les valeurs des fichiers précédents, clé par clé. C’est la méthode standard pour conserver un fichier de base avec une petite surcharge de configuration pour la production. Les règles diffèrent toutefois pour les listes et les maps. Consultez donc la fusion de plusieurs fichiers Compose avant de diagnostiquer un comportement inattendu.

--profile démarre les services associés à ce profil en plus des services sans profil. Cela permet de garder les outils de débogage hors d’un up normal. -p définit le nom du projet. Deux copies d’une même stack peuvent ainsi s’exécuter côte à côte avec des réseaux et des noms de volumes distincts. Pour restaurer la stack après un redémarrage, vous ne saisissez pas de commande. Une unit s’en charge automatiquement, comme décrit dans démarrer des stacks Compose au démarrage.

FAQ

Qu’est-ce qui a remplacé docker-compose par un espace ?

Compose V2, appelé avec docker compose et un espace. Il s’agit d’un plugin fourni avec Docker Engine, et l’outil Python V1 n’est plus installé par les paquets actuels. Si la commande avec espace n’affiche rien, installez le paquet docker-compose-plugin correspondant à votre distribution. Mettez à jour les anciens scripts pour utiliser la forme avec espace plutôt que d’ajouter un alias, car V2 possède des options que V1 n’avait pas.

Pourquoi docker compose restart ne prend-il pas en compte ma modification de configuration ?

restart arrête et redémarre le conteneur existant avec la configuration utilisée lors de sa création. Il ne relit jamais compose.yaml. Toute modification des variables d’environnement, des ports, des volumes ou du tag de l’image nécessite docker compose up -d. Cette commande compare chaque service à son conteneur en cours d’exécution et recrée ceux qui diffèrent. Ajoutez --force-recreate lorsque vous voulez forcer le remplacement, même si aucun élément du fichier n’a changé.

Comment mettre à jour un service vers une image plus récente ?

Exécutez docker compose pull, puis docker compose up -d. La commande pull récupère l’image actuelle correspondant à chaque tag du fichier, et up -d recrée tout service dont l’identifiant d’image ne correspond plus à celui de son conteneur. Exécuter up -d seul réutilise l’image déjà présente sur le disque. C’est pourquoi une stack épinglée sur latest peut continuer à utiliser une build vieille de plusieurs mois sans afficher d’erreur.

Quelles commandes de nettoyage sont sûres sur un serveur en production ?

docker system df, docker image prune -a et docker builder prune suppriment uniquement les images et le cache. Les services en cours d’exécution continuent donc de fonctionner et les volumes nommés restent inchangés. Le couple dangereux est docker compose down -v et docker volume prune, qui supprime les volumes nommés sans demander de confirmation. Exécutez d’abord docker compose config --volumes pour connaître les éléments exposés.

Puis-je exécuter une seule commande sans démarrer toute la stack ?

Oui. docker compose run --rm --no-deps web sh démarre un seul conteneur à partir de la définition du service web, ignore ses dépendances et supprime le conteneur lorsque vous quittez. Utilisez plutôt exec lorsque le conteneur est déjà en cours d’exécution, car exec se connecte au processus actif et affiche l’état réel du service.