Docker Compose : comprendre son fonctionnement

Auteur : Rédaction Domeny.ForSale Publié le 05.10.2026

En bref : Docker Compose est un outil permettant de définir et de lancer des applications composées de plusieurs conteneurs Docker. Vous décrivez dans un seul fichier les services, leur configuration, leurs connexions et le stockage de leurs données, puis vous les lancez avec la commande docker compose up. Il est utile, par exemple, lorsqu’un projet nécessite une application, une base de données et une interface d’administration supplémentaire.

Comment Docker Compose fonctionne avec Docker

Docker exécute les programmes dans des conteneurs, des environnements isolés contenant l’application et les dépendances dont elle a besoin. Un conteneur est créé à partir d’une image : un paquet prêt à l’emploi qui définit ce qui doit être exécuté. Compose ne remplace pas Docker : il s’appuie sur lui pour gérer un ensemble de conteneurs liés entre eux.

Sans Compose, vous pouvez lancer chaque conteneur avec une commande docker run distincte, en précisant manuellement les ports, les variables d’environnement et le réseau. Compose permet d’enregistrer ces paramètres dans le fichier compose.yaml. Vous pouvez ainsi conserver la configuration avec le code du projet et la reproduire sur un autre ordinateur.

Le concept central est le service, qui définit un élément précis de l’environnement, par exemple une base de données. Compose crée les conteneurs à partir de ces définitions. Par défaut, il crée aussi un réseau pour le projet, dans lequel les services peuvent se trouver grâce à leur nom.

Que contient le fichier compose.yaml ?

La configuration s’écrit en YAML, un format texte dont la structure repose sur l’indentation. Celle-ci doit être cohérente : utilisez des espaces, et non des tabulations.

Vous rencontrerez le plus souvent les éléments suivants :

services — la liste des services qui composent l’environnement.
image — l’image à partir de laquelle le conteneur sera lancé ; une autre possibilité est build, qui indique comment construire votre propre image.
ports — l’association d’un port de l’ordinateur à un port du conteneur, qui permet d’accéder au service depuis l’extérieur du réseau des conteneurs.
environment — les variables d’environnement qui configurent le programme.
volumes — le montage de répertoires ou de volumes, des espaces de stockage dont les données sont conservées indépendamment du cycle de vie du conteneur.

Le simple démarrage des conteneurs ne signifie pas encore que l’application fonctionne correctement. La base de données peut avoir besoin de temps pour s’initialiser, et l’application doit être capable de retenter la connexion. depends_on peut définir l’ordre de démarrage, mais sa forme de base ne garantit pas qu’un service soit prêt. Pour cela, il faut configurer correctement le contrôle d’état, appelé healthcheck, ainsi que la condition de dépendance.

Exemple : PostgreSQL et une interface de gestion de la base

Supposons que vous souhaitiez tester PostgreSQL localement sans installer la base de données directement sur votre système. Vous avez également besoin de l’interface Adminer, qui permet de consulter les données dans un navigateur. Créez un répertoire de projet et enregistrez-y le fichier compose.yaml :

services:
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: demo
      POSTGRES_PASSWORD: mot_de_passe_demo_local
      POSTGRES_DB: demo
    volumes:
      - db_data:/var/lib/postgresql/data

  adminer:
    image: adminer:5
    ports:
      - "127.0.0.1:8080:8080"

volumes:
  db_data:

Lancez l’environnement depuis ce répertoire :

docker compose up -d

L’option -d lance les conteneurs en arrière-plan. Au premier démarrage, Docker téléchargera les images si elles ne sont pas présentes localement.

Ouvrez l’adresse http://localhost:8080 dans votre navigateur. Dans l’interface, sélectionnez PostgreSQL, puis saisissez le serveur db, l’utilisateur demo, le mot de passe mot_de_passe_demo_local et la base demo. Si la base est encore en cours d’initialisation, attendez un peu et réessayez de vous connecter.

Le nom db fonctionne à l’intérieur du réseau Compose. N’utilisez pas localhost à cet endroit : du point de vue du conteneur Adminer, ce nom désignerait le conteneur Adminer lui-même, et non la base de données. Dans cet exemple, aucun port de PostgreSQL n’est exposé sur l’ordinateur, tandis que l’interface d’administration n’est accessible que par l’interface réseau locale de l’ordinateur.

Cette configuration sert à apprendre ; elle n’est pas prête pour la production. N’utilisez pas le mot de passe d’exemple pour des données réelles et n’enregistrez pas de véritables secrets dans le dépôt.

Les commandes utiles au quotidien

La commande actuelle s’écrit docker compose, avec une espace. La forme docker-compose, présente dans les anciens guides, correspond à l’ancien mode d’installation de l’outil. Pour vérifier que Compose est disponible, utilisez docker compose version. Si la commande ne fonctionne pas, vérifiez la procédure d’installation adaptée à votre système dans la documentation officielle de Docker.

Commande	Utilisation
`docker compose ps`	Affiche les conteneurs du projet et leur état.
`docker compose logs -f`	Affiche les journaux et suit les nouveaux messages.
`docker compose stop`	Arrête les conteneurs sans les supprimer.
`docker compose down`	Supprime les conteneurs et le réseau du projet, mais conserve par défaut les volumes nommés.
`docker compose config`	Vérifie et affiche la configuration résultante.

Attention à docker compose down -v : l’option -v supprime également les volumes gérés par le projet. Dans cet exemple, elle effacera donc les données de la base. Un volume permet de conserver les données après la suppression du conteneur, mais ne remplace pas une sauvegarde.

Quand Compose suffit, et quand il ne suffit pas

Compose convient bien au développement local d’applications, aux tests d’intégration et aux déploiements simples sur un seul serveur. Il est particulièrement utile lorsque plusieurs personnes doivent lancer le même ensemble de services sans reproduire manuellement les paramètres.

À lui seul, il n’assure ni la gestion d’un cluster de plusieurs serveurs ni la haute disponibilité. Un déploiement en production exige de prévoir séparément la sécurité, les sauvegardes, la surveillance et les mises à jour des images. Un tag d’image tel que postgres:17 peut désigner des versions successives d’une même branche. Si vous avez besoin d’une reproductibilité stricte, envisagez de fixer l’image à un digest précis, c’est-à-dire à un identifiant de son contenu.

Pour commencer, lancez l’exemple, consultez les journaux et exécutez docker compose down, puis à nouveau docker compose up -d. Vous constaterez ainsi concrètement la différence entre un conteneur recréé et des données conservées.