Docker Compose : écrire un fichier compose.yaml

Docker Compose est l'outil qui décrit une application de plusieurs conteneurs dans un seul fichier YAML, compose.yaml, et qui la démarre, la met à jour ou l'arrête d'une seule commande (docker compose up -d). Ce chapitre présente la syntaxe actuelle (sans la clé version, devenue obsolète), les clés d'un service, les volumes et les réseaux, les variables d'environnement et le fichier .env, l'ordre de démarrage avec les contrôles de santé, puis les commandes du quotidien.

Pourquoi Compose

Lancer l'API et sa base à la main demande déjà quatre commandes longues : un réseau, un volume, deux docker run avec leurs options. Les retaper à l'identique à chaque mise à jour, sur chaque serveur, est source d'erreurs. Compose remplace ces commandes par un fichier déclaratif : tu décris l'état voulu (quels services, avec quelles images, quels volumes, quels réseaux), et docker compose up -d crée ou recrée ce qui doit l'être. Le fichier se versionne avec le code dans Git : c'est la documentation exacte du déploiement.

Compose aujourd'hui : ce qui a changé

Avec un fichier qui commence encore par version:, Compose avertit :

WARN[0000] /srv/gestion/docker-compose.yml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion

Supprime simplement la ligne : Compose valide toujours le fichier avec le schéma le plus récent, quelle que soit la valeur écrite.

Un premier fichier compose.yaml

Voici l'API sorbier-frais et sa base, pour un environnement de développement :

# compose.yaml
services:
  api:
    build: .
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DB_HOST: bdd
      DB_NAME: frais
      DB_USER: frais
      DB_PASSWORD: ${DB_PASSWORD:?définis DB_PASSWORD dans .env}
    depends_on:
      bdd:
        condition: service_healthy
    restart: unless-stopped

  bdd:
    image: mysql:8.4
    environment:
      MYSQL_DATABASE: frais
      MYSQL_USER: frais
      MYSQL_PASSWORD: ${DB_PASSWORD:?définis DB_PASSWORD dans .env}
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:?définis DB_ROOT_PASSWORD dans .env}
    volumes:
      - mysql-donnees:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    restart: unless-stopped

volumes:
  mysql-donnees:

Et à côté, le fichier .env, jamais versionné (ajoute-le au .gitignore) :

DB_PASSWORD=7uQ2-mVx9-Lr4k-Zp8s
DB_ROOT_PASSWORD=Jw3n-Tb6c-Hq1e-Fy5d

YAML se lit à l'indentation : deux espaces par niveau, jamais de tabulation, et un tiret pour chaque élément de liste.

Les commandes du quotidien

Toutes les commandes se lancent dans le dossier du compose.yaml :

docker compose up -d

[+] Running 4/4
 ✔ Network sorbier-frais_default      Created     0.1s
 ✔ Volume sorbier-frais_mysql-donnees Created     0.0s
 ✔ Container sorbier-frais-bdd-1      Healthy    21.4s
 ✔ Container sorbier-frais-api-1      Started    21.6s

Le projet, ses noms et son réseau

Compose regroupe tout sous un nom de projet, par défaut le nom du dossier (sorbier-frais ici), et nomme les objets à partir de lui :

Tous les services d'un projet sont branchés sur son réseau par défaut et se joignent par leur nom de service. Fixe le nom avec la clé name: sorbier-frais en tête de fichier, pour qu'il ne dépende pas du dossier. Évite container_name: : un nom fixe empêche de lancer deux copies du projet et n'apporte rien, puisqu'on désigne les services par leur nom dans toutes les commandes docker compose.

Attendre qu'un service soit prêt

depends_on seul ne fait qu'ordonner le lancement : l'API démarre dès que le conteneur de la base est lancé, alors que MySQL met une vingtaine de secondes à initialiser sa base la première fois. L'API tente de se connecter, échoue et s'arrête.

Avec condition: service_healthy, Compose attend que le contrôle de santé de la base réussisse. Le test mysqladmin ping -h 127.0.0.1 passe par TCP : pendant l'initialisation, l'image fait tourner un serveur temporaire qui n'écoute pas le réseau, donc le test échoue tant que le vrai serveur n'est pas prêt. mysqladmin ping renvoie 0 dès que le serveur répond, même s'il refuse l'authentification : aucun mot de passe n'est nécessaire dans le test.

Variables, .env et env_file

Compose lit le fichier .env du dossier du projet et s'en sert pour remplacer les ${VAR} du compose.yaml. Ce fichier ne passe pas tel quel dans les conteneurs : seules les variables listées sous environment: y arrivent.

La clé env_file: est différente : elle charge un fichier de variables directement dans le conteneur, sans passer par le remplacement. Elle sert pour une longue liste de réglages applicatifs.

services:
  api:
    env_file: config/api.env

Vérifie toujours le résultat avant de lancer :

docker compose config

La commande affiche le fichier complet, variables remplacées, ou l'erreur exacte (indentation, variable manquante).

Les autres clés utiles

Plusieurs fichiers. Compose fusionne automatiquement compose.yaml et compose.override.yaml s'il existe. On garde ainsi un fichier commun et un fichier de surcharge pour le développement (ports publiés, montage du code). En production, on précise les fichiers : docker compose -f compose.yaml -f compose.prod.yaml up -d.

Compose Watch. En développement, la section develop.watch d'un service synchronise les fichiers modifiés dans le conteneur, ou reconstruit l'image, pendant que docker compose watch tourne : une alternative au montage du code.

Mettre à jour une application

docker compose pull          # nouvelles images (services avec image:)
docker compose build         # nouvelles images construites (services avec build:)
docker compose up -d         # recrée uniquement les services dont l'image ou la config a changé
docker image prune           # supprime les anciennes images sans étiquette

up -d compare l'état voulu à l'état réel : un service dont rien n'a changé n'est pas touché. Le volume de la base est conservé, puisqu'il n'est pas supprimé par la recréation des conteneurs.

Exercices

version: "3.7"
services:
  web:
    build: .
    container_name: web
    ports:
      - "80:3000"
    links:
      - db
    depends_on:
      - db
    environment:
      - DB_HOST=db
      - DB_PASSWORD=secret123
  db:
    image: mysql
    environment:
      - MYSQL_ROOT_PASSWORD=secret123

services:
  web:
    build: .
    ports:
      - "80:3000"
    environment:
      DB_HOST: db
      DB_PASSWORD: ${DB_PASSWORD:?définis DB_PASSWORD dans .env}
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: mysql:8.4
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_PASSWORD:?définis DB_PASSWORD dans .env}
    volumes:
      - db-donnees:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    restart: unless-stopped

volumes:
  db-donnees:

docker network create wiki_default
docker volume create wiki_pages
docker run -d --name wiki-app-1 --network wiki_default \
  -p 127.0.0.1:8081:80 -v wiki_pages:/var/www/html/data \
  -e TZ=Europe/Paris --restart unless-stopped \
  ghcr.io/sorbier/wiki:1.4

name: wiki

services:
  app:
    image: ghcr.io/sorbier/wiki:1.4
    ports:
      - "127.0.0.1:8081:80"
    volumes:
      - pages:/var/www/html/data
    environment:
      TZ: Europe/Paris
    restart: unless-stopped

volumes:
  pages: