Docker Compose : commandes utiles sur serveur

Les commandes Compose que vous utilisez réellement

Docker Compose fournit plus de quarante sous-commandes. Au quotidien, l’administration d’un serveur en utilise environ une douzaine. Cette page les regroupe selon l’opération à 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 a disparu des paquets actuels. Un docker-compose: command not found sur une nouvelle installation Ubuntu en juillet 2026 est donc attendu et n’indique pas un problème. Vérifiez avec docker compose version. Si cette commande n’affiche rien, installez le paquet docker-compose-plugin.

Toutes les commandes ci-dessous doivent être exécutées depuis le répertoire qui contient votre compose.yaml, car Compose déduit le nom du projet 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 saisirez 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 rend la main. La commande rend la main dès que les conteneurs sont créés, ce qui explique pourquoi un script de déploiement qui exécute ensuite une sonde curl échoue souvent au premier essai. up -d --wait bloque jusqu’à ce que chaque service qui déclare un healthcheck soit indiqué comme sain, puis retourne un code différent de zéro si l’un d’eux n’atteint jamais cet état. Le résultat dépend entièrement du contrôle exécuté ; écrivez donc un healthcheck que Compose peut utiliser de manière fiable avant de vous appuyer dessus dans l’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 le malentendu le plus coûteux avec Compose ; la différence complète entre down et stop explique dans quels cas il 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 modification du mapping de port n’a donc aucun effet. Pour appliquer une modification du fichier, exécutez à 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, télécharger 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 aucun élément n’a changé, ce qui permet de l’exécuter plusieurs fois sans risque. --force-recreate force la comparaison à ignorer cet état et remplace chaque conteneur, même si la configuration est identique. C’est donc le moyen le plus rapide de supprimer un état incohérent dans un conteneur.

La mise à jour d’une image nécessite 2 commandes, car elles effectuent 2 opérations différentes. pull télécharge l’image actuelle correspondant à 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 le recrée. Si vous omettez le pull, up -d continue d’utiliser le 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 l’image et démarre le service en une seule étape. C’est la boucle normale pendant que vous modifiez le code. Utilisez --no-cache uniquement lorsqu’une couche mise en cache est clairement obsolète, car cette commande reconstruit toutes les couches depuis zéro.

Vérifier ce qui fonctionne

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 a échoué au démarrage n’y apparaît pas tant que vous n’ajoutez pas -a. Ainsi, lorsqu’un conteneur est absent de ps alors que ps -a l’affiche avec l’état Exited (1), il s’agit généralement d’un échec au démarrage. Lisez le code de sortie, puis consultez les journaux.

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 le nom d’un service pour limiter l’affichage. --tail=100 est utile pour un conteneur actif depuis un mois, car l’affichage par défaut montre tout l’historique et surcharge le terminal. --since 15m répond généralement à la question que vous vous posez : que s’est-il passé pendant le redémarrage que vous venez d’effectuer ?

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

Obtenir 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. C’est nécessaire lorsque le service ne reste pas actif assez longtemps pour permettre l’utilisation de exec. Associez toujours run à --rm. Sans cette option, chaque exécution laisse derrière elle un conteneur arrêté, et ces conteneurs 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. Ajouter --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 transmis à un service, une fois chaque fichier .env, bloc environment: et variable shell fusionnés. Lorsqu’une valeur est incorrecte, l’ordre de fusion est généralement en cause. la résolution des fichiers env et des secrets par Compose précise 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, et chaque nom de service correspond à 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. Elle permet donc de 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é. Cela évite de devoir deviner la correspondance lorsqu’elle provient d’une variable. La publication d’un port ajoute également une règle de pare-feu gérée directement par Docker. 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 les raisons pour lesquelles 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 volumes à 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. C’est la bonne commande pour supprimer une stack de test, mais la mauvaise dès qu’elle contient des données importantes, car aucune confirmation ni annulation n’est possible. Les bind mounts y survivent, puisqu’ils se trouvent dans le système de fichiers de l’hôte. Cette différence au niveau de l’impact est l’une des raisons pour lesquelles il faut choisir délibérément entre bind mounts et 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 qui appartiennent 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 fonctionner et restent invisibles pour docker compose ps.

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

Aucune de ces commandes ne touche aux volumes nommés. 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 succès. Utilisez-le donc dans une étape de pre-deploy ou un git hook. La commande config affiche le fichier entièrement fusionné et interpolé. Elle permet de confirmer qu’une variable a été résolue et qu’un fichier d’override a été appliqué comme prévu. Une variable non définie apparaît alors avec une valeur vide, accompagnée 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. La commande affiche toutes les actions que Compose effectuerait, sans rien modifier. Ces trente secondes sont bien investies avant un down sur une stack importante.

Utiliser 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. 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 rechercher la cause d’un résultat inattendu.

--profile démarre les services associés à ce profil en plus des services sans profil. Les outils de débogage restent ainsi exclus d’un up normal. -p définit le nom du projet. Deux copies d’une même stack peuvent donc 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. Il faut utiliser une unité qui l’exécute automatiquement, comme décrit dans démarrer les stacks Compose au boot.

FAQ

Qu’est-ce qui a remplacé docker-compose avec un trait d’union ?

Compose V2, appelé avec docker compose en utilisant 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 forme 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 propose des options absentes de V1.

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

restart arrête puis 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 pour forcer le remplacement même si le fichier n’a pas 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’ID 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 utilisant latest peut rester sur un build vieux 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 ne sont pas modifié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 savoir ce qui est exposé.

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 la commande. Utilisez plutôt exec si le conteneur est déjà en cours d’exécution, car exec se rattache au processus actif et vous montre l’état réel du service.