Qu'est-ce que Docker Compose et Comment l'Utiliser

Le problème que Compose résout

Une vraie application, c’est rarement un seul conteneur. Une API web a besoin d’une base de données, la base de données a besoin d’un volume pour que ses données survivent à un redémarrage, puis vous ajoutez un cache Redis et un worker en arrière-plan. Cela fait quatre commandes docker run, chacune avec ses options pour les ports, les volumes, les variables d’environnement et un réseau partagé. Dans le bon ordre. Chaque fois que vous vous remettez au travail.

Docker Compose remplace ces commandes par un fichier et une commande. Vous décrivez les conteneurs et la façon dont ils se connectent dans un fichier nommé compose.yaml, et docker compose up les lance tous. Si vous n’avez jamais utilisé les images ni docker run, commencez par ce qu’est Docker et comment fonctionnent les conteneurs.

Ce que décrit le fichier compose

Un fichier compose comporte une poignée de clés de premier niveau. Celle que vous utilisez toujours est services : chaque service est un conteneur que Compose va exécuter.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/app
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:18
    volumes:
      - db-data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  db-data:

Deux conteneurs. api est construit à partir du Dockerfile du répertoire courant et publie le port 8000. db exécute l’image officielle postgres:18 et conserve ses données dans un volume nommé, si bien que les données sont toujours présentes lorsque le conteneur est recréé.

Deux détails font le vrai travail ici :

• api atteint db via le nom d’hôte db. Compose place chaque service sur un réseau partagé et enregistre le nom de chaque service comme nom DNS. Pas d’adresses IP, pas de --link à l’ancienne. DATABASE_URL pointe vers db:5432 et Compose résout le nom.
• depends_on avec condition: service_healthy retient api jusqu’à ce que Postgres réponde vraiment. Un depends_on simple attend seulement que le conteneur démarre, pas que le processus de base de données à l’intérieur accepte les connexions : cet écart est la cause la plus fréquente d’un « connection refused » au premier démarrage.

Les trois clés principales : services, volumes, networks

Trois clés de premier niveau correspondent à des concepts Docker que vous connaissez déjà :

networks, vous le déclarez rarement. Compose crée un réseau par projet et y rattache chaque service. Voilà pourquoi l’exemple avec Postgres n’a demandé aucune configuration réseau. Ne déclarez des réseaux explicitement que lorsque vous voulez empêcher des groupes de services de s’atteindre :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

services:
  api:
    build: .
    networks: [frontend, backend]
  db:
    image: postgres:18
    networks: [backend]        # not reachable from frontend
  proxy:
    image: caddy:2
    networks: [frontend]

networks:
  frontend:
  backend:

Les commandes que vous utiliserez vraiment

Exécutez-les depuis le répertoire qui contient compose.yaml.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# Tout lancer, les logs affichés dans le terminal
docker compose up

# Lancer en arrière-plan
docker compose up -d

# Reconstruire les images qui ont une section build, puis lancer
docker compose up --build

# Arrêter et supprimer conteneurs et réseaux (les volumes nommés sont conservés)
docker compose down

# Pareil, et supprimer aussi les volumes nommés
docker compose down -v

# Ce qui tourne pour ce projet
docker compose ps

# Suivre les logs d'un service
docker compose logs -f api

# Commande ponctuelle dans un nouveau conteneur
docker compose run --rm api python manage.py migrate

# Shell dans un conteneur déjà en cours d'exécution
docker compose exec api bash

up et down sont le duo que vous tapez le plus. Vous pouvez relancer up sans risque : après une modification du fichier, il ne recrée que les services dont la configuration a changé et laisse les autres tranquilles.

Ce que docker compose up affiche au premier lancement

Lancez l’exemple avec Postgres ci-dessus et vous obtenez à peu près ceci :

1
2
3
4
5

[+] Running 4/4
 ✔ Network app_default    Created
 ✔ Volume "app_db-data"   Created
 ✔ Container app-db-1      Healthy
 ✔ Container app-api-1     Started

Compose fait précéder chaque nom de celui du projet (le répertoire, par défaut) et le fait suivre d’un numéro, parce qu’il peut lancer plusieurs répliques d’un même service. app-db-1 passe à Healthy avant que app-api-1 démarre : c’est condition: service_healthy qui fait son travail.

Comment garder les mots de passe hors du fichier compose

Compose lit un fichier nommé .env dans le répertoire du projet et remplace les références ${VAR} dans le fichier compose :

1
2
3
4
5

services:
  db:
    image: postgres:18
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

1
2

# .env  — ajoutez ce fichier à .gitignore
DB_PASSWORD=secret

Gardez .env hors du contrôle de version et versionnez à la place un .env.example avec des valeurs vides ou factices. Pour tout ce qui est réellement sensible dans un environnement déployé, utilisez les Docker secrets plutôt que des variables d’environnement.

Services optionnels avec les profiles

Tous les services n’ont pas à démarrer à chaque fois. Une entrée profiles garde un service inactif tant que vous ne le demandez pas :

1
2
3
4
5
6
7
8
9

services:
  api:
    build: .
  db:
    image: postgres:18
  seed:
    build: .
    command: python manage.py seed_demo_data
    profiles: [tools]

docker compose up démarre api et db et ignore complètement seed. docker compose --profile tools run --rm seed exécute le seeder quand vous le demandez. Utilisez les profiles pour tout ce qui est ponctuel : seeders, migrations, un shell de débogage, un générateur de charge que vous ne voulez que pendant un test.

Compose v2 vs l’ancien docker-compose

Si un guide vous dit d’exécuter docker-compose avec un tiret, il est antérieur à 2023. C’était la v1, écrite en Python, aujourd’hui en fin de vie. L’outil actuel est docker compose en tant que sous-commande de la CLI Docker ; il est fourni avec Docker Desktop et avec le paquet du plugin Compose pour Docker Engine.

Les anciens fichiers ont souvent cette ligne en tête :

1

version: "3.8"   # delete it

La clé version n’a aucun effet dans Compose v2. Compose valide selon la Compose Specification actuelle et vous avertit quand la clé est présente. Retirez-la et l’avertissement disparaît.

Le nom de fichier par défaut a changé lui aussi : compose.yaml est le nom actuel, docker-compose.yml fonctionne encore, et Compose accepte les deux.

Rechargement à chaud pendant le développement

docker compose watch (Compose 2.22 et suivants) met à jour les conteneurs pendant que vous éditez. Ajoutez un bloc develop au service :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

services:
  api:
    build: .
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: rebuild
          path: ./requirements.txt

sync copie les fichiers modifiés directement dans le conteneur en cours d’exécution, donc une modification de code est prise en compte sans reconstruction. rebuild déclenche une reconstruction complète de l’image quand un fichier qui influe sur le build change, comme un fichier de verrouillage des dépendances. Lancez-le avec docker compose watch, ou ajoutez --watch à up.

Quand Compose est le mauvais outil

Compose exécute des conteneurs sur une seule machine. C’est là que Compose s’arrête, et l’essentiel de ce qui lui manque se trouve juste après.

Il convient au développement local, aux tests automatisés en CI et aux petits déploiements sur un seul hôte. Il ne sait pas planifier des conteneurs sur plusieurs serveurs, en remplacer un quand un nœud tombe, faire des déploiements progressifs conditionnés aux healthchecks, ni autoscaler.

C’est le travail d’un orchestrateur : Kubernetes, ou Docker Swarm si vous voulez plus léger. Les deux ne sont pas en concurrence. Un fichier compose est souvent le brouillon qui devient ensuite un jeu de manifestes Kubernetes, et beaucoup d’équipes continuent d’utiliser Compose en local longtemps après que la production est passée sur un cluster.

Podman n’est pas en reste : podman compose et podman-compose lisent le même format de fichier, avec les réserves détaillées dans Docker vs Podman.

Erreurs courantes

• Des secrets versionnés dans compose.yaml. Le fichier finit dans Git. Utilisez .env (dans gitignore) ou Docker secrets.
• Se fier à depends_on pour attendre qu’un service soit prêt. Seul, il attend que le conteneur démarre, pas que le service accepte les connexions. Associez-le à un healthcheck et condition: service_healthy.
• Définir container_name. Cela vous empêche d’exécuter plusieurs copies du projet et casse docker compose up --scale. Laissez Compose nommer les conteneurs.
• Faire un bind mount par-dessus un répertoire de dépendances installées. Monter le dossier du projet dans un conteneur Node ou Python peut masquer le node_modules ou le virtualenv créé pendant le build. Montez des sous-dossiers du code source, ou placez un volume anonyme sur le chemin des dépendances.

Comment faire passer une application existante sur Compose

Prenez l’application que vous démarrez aujourd’hui avec un script plein de lignes docker run et faites-la passer dans un compose.yaml, un service à la fois. Lancez-la, lisez les logs, corrigez ce qui casse, ajoutez le service suivant. Donnez un healthcheck à tout ce dont d’autres services dépendent : c’est l’étape qu’on saute, et c’est celle qui arrête le « connection refused » au démarrage à froid.

Vous saurez que c’est bon quand docker compose down -v && docker compose up reconstruit tout l’environnement à partir de rien et que l’application revient à l’identique à chaque fois.

Articles associés

• Qu’est-ce que Docker et à quoi ça sert
• Qu’est-ce qu’un volume Docker
• Docker vs Podman : lequel choisir
• Qu’est-ce que Kubernetes et à quoi ça sert