7. Docker Compose

7.1 Pourquoi Docker Compose ?

Un conteneur répond à un besoin précis : exécuter un processus dans un environnement isolé. Une application complète comprend souvent plusieurs composants : un serveur web, une API, une base de données, un cache ou un service de traitement.

Avec Docker seul, chaque conteneur peut être géré séparément. Mais il faut alors conserver la cohérence des paramètres : réseaux, volumes, ports, variables et ordre de démarrage.

Docker Compose permet de décrire cet ensemble dans un fichier de configuration, puis de gérer les services comme un projet. Compose ne remplace pas Docker Engine : il s'appuie sur lui pour créer et gérer les objets Docker.

7.2 Le modèle déclaratif et le projet Compose

Compose adopte une approche déclarative : on décrit la configuration attendue de l'application plutôt que d'énumérer toutes les étapes de création de chaque conteneur.

Le fichier Compose est une déclaration de configuration, pas une photographie de l'état réel. Compose interprète cette déclaration et demande à Docker Engine les opérations nécessaires lors des commandes de gestion.

Le nom du projet sert notamment à regrouper et identifier les ressources. Plusieurs projets Compose peuvent cohabiter sur une même machine, avec des noms et des ressources distincts.

7.3 La structure d’un fichier compose.yaml

Le fichier usuel est compose.yaml (ou compose.yml). Il utilise le format YAML, où l'indentation structure les relations entre les éléments.

Et si nous reprenions notre exemple d’architecture comme fil rouge pour découvrir le fichier compose.yaml ?

Un fichier Compose regroupe les définitions des services et les ressources partagées du projet. Voici une vue simplifiée de sa structure :

services:
  nom_de_mon_service:
    image: mon_image:semver
    ports: (...)
    environment: (...)
    secrets: (...)
    volumes: (...)
    networks: (...)
    healthcheck: (...)
    depends_on: (...)

networks: (...)

volumes: (...)

secrets: (...)

Explication du fichier Compose :

Un exemple complet sera présenté en 7.11 — Scénario : NGINX, WordPress et MariaDB, après l’explication de ces notions.

7.4 Services, images et construction

Un service Compose définit la façon dont un composant doit être exécuté. Il peut préciser l'image, la commande, les variables, les ports, les montages et les réseaux.

Deux modes d'obtention de l'image sont fréquents :

1. image: nginx:stable : Référence une image par son nom et son tag.

   services:
     web:
       image: nginx:stable

2. build: ./api : Décrit un contexte de construction local, généralement associé à un Dockerfile.

   services:
     api:
       build: ./api

   Le chemin ./api désigne le contexte de construction, relatif au fichier Compose. Par défaut, Compose y cherche un fichier nommé Dockerfile.

   Exemple minimal de ./api/Dockerfile :

   FROM nginx:stable-alpine
   COPY index.html /usr/share/nginx/html/index.html

   FROM choisit l’image de base. COPY copie le fichier ./api/index.html dans l’image construite, à l’emplacement servi par NGINX.

   Ainsi, build: ./api fournit le dossier de construction ; ./api/Dockerfile décrit comment construire l’image du service api. Le nom api est ici un nom de service : cet exemple minimal sert une page HTML.

7.5 Réseaux et communication entre services

Compose crée généralement un réseau par défaut propre au projet.

Les services connectés à un même réseau peuvent communiquer entre eux en utilisant leur nom de service comme nom DNS, sans dépendre d'une adresse IP de conteneur susceptible de changer.

1. Déclarer les réseaux et y connecter les services

Dans notre architecture, nous choisissons deux réseaux explicites. Voici uniquement les éléments concernés du fichier Compose :

services:
  web:
    networks:
      - frontend

  app:
    networks:
      - frontend
      - backend

  db:
    networks:
      - backend

networks:
  frontend:
  backend:

La clé networks au niveau racine déclare les deux réseaux du projet. Sous chaque service, networks indique à quels réseaux ses conteneurs sont connectés.

• web peut joindre app sur frontend. NGINX utilise l’adresse app:80 dans sa configuration.
• app peut joindre db sur backend. WordPress utilise l’adresse db:3306 pour sa connexion à MariaDB.
• web est uniquement sur frontend et db uniquement sur backend : ils ne partagent aucun réseau.

Connecter app aux deux réseaux ne crée pas automatiquement une liaison réseau directe entre web et db. Voir le chapitre 5, section 5.2.4 — Règles de communication et sécurisation.

2. Publier un port sur l’hôte

services:
  web:
    ports:
      - "8080:80"

La clé ports est placée sous le service web. La valeur "8080:80" associe le port 8080 de l’hôte au port 80 du conteneur NGINX.

Grâce à cette publication, le client sur l’hôte peut atteindre NGINX à l’adresse localhost:8080. Sans elle, une connexion à localhost:8080 ne serait pas transmise au port 80 du conteneur web.

Pour approfondir la différence entre port interne et port publié, voir le chapitre 5, section 5.3 — Ports et exposition des services.

7.6 Volumes et persistance des données

Les données écrites dans la couche modifiable d’un conteneur sont perdues lorsque ce conteneur est supprimé. Notre architecture utilise donc des montages pour fournir la configuration et conserver les données.

1. Fournir un fichier de l’hôte : le bind mount

services:
  web:
    volumes:
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro

1. ./nginx/default.conf est le fichier source sur l’hôte, dont le chemin est relatif au fichier Compose.
2. /etc/nginx/conf.d/default.conf est son emplacement dans le conteneur.
3. :ro rend ce montage accessible en lecture seule dans le conteneur.

NGINX lit ainsi la configuration fournie par l’hôte, sans reconstruire son image. Ce montage fournit un fichier ; il ne décrit pas lui-même le comportement du serveur.

2. Conserver les données : les volumes nommés

services:
  app:
    volumes:
      - wordpress_data:/var/www/html

  db:
    volumes:
      - db_data:/var/lib/mysql

volumes:
  wordpress_data:
  db_data:

1. Au niveau racine, volumes déclare les volumes nommés du projet.
2. Sous app, wordpress_data est monté dans /var/www/html pour conserver les fichiers WordPress.
3. Sous db, db_data est monté dans /var/lib/mysql pour conserver les données MariaDB.

Pour aller plus loin : Compose peut référencer un volume déclaré comme external, déjà existant et dont le cycle de vie est géré en dehors du projet. Ce n’est pas le cas des deux volumes de notre scénario.

7.7 Configuration, variables et secrets

La configuration peut être fournie au démarrage, sans être intégrée à l’image. Notre scénario distingue les paramètres ordinaires et les mots de passe.

1. Fournir les paramètres avec environment

services:
  app:
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD_FILE: /run/secrets/db_password

  db:
    environment:
      MARIADB_DATABASE: wordpress
      MARIADB_USER: wordpress
      MARIADB_PASSWORD_FILE: /run/secrets/db_password
      MARIADB_ROOT_PASSWORD_FILE: /run/secrets/db_root_password

Ces noms de variables sont reconnus par les images WordPress et MariaDB : Compose les transmet, et les images définissent leur signification.

2. Déclarer les secrets et les attribuer aux services

services:
  app:
    secrets:
      - db_password

  db:
    secrets:
      - db_password
      - db_root_password

secrets:
  db_password:
    file: ./secrets/db_password.txt
  db_root_password:
    file: ./secrets/db_root_password.txt

1. Au niveau racine, secrets déclare les secrets et leurs fichiers sources sur l’hôte.
2. Sous chaque service, secrets accorde l’accès aux secrets nécessaires : app reçoit le mot de passe applicatif ; db reçoit les deux. web ne reçoit aucun secret.
3. Compose les rend accessibles dans les conteneurs sous /run/secrets/db_password et, pour MariaDB uniquement, /run/secrets/db_root_password.
4. Les variables _FILE de l’extrait précédent indiquent aux images où lire ces mots de passe. Ce suffixe est une convention prise en charge par ces images, pas un mécanisme universel de Compose.

3. Utiliser l’interpolation

Exemple d’interpolation d’une valeur non sensible

À côté de compose.yaml, le fichier .env peut contenir :

DB_NAME=wordpress

Compose peut utiliser cette valeur dans le fichier YAML :

services:
  app:
    environment:
      WORDPRESS_DB_NAME: ${DB_NAME}

  db:
    environment:
      MARIADB_DATABASE: ${DB_NAME}

1. Compose lit DB_NAME depuis son environnement ou le fichier .env ; une valeur dans son environnement est prioritaire.
2. Il remplace ${DB_NAME} par wordpress avant de créer les conteneurs : c’est l’interpolation.
3. La clé environment transmet ensuite WORDPRESS_DB_NAME=wordpress à WordPress et MARIADB_DATABASE=wordpress à MariaDB. Le nom DB_NAME n’est pas automatiquement transmis aux conteneurs.

Pour l’interpolation, seules les variables référencées dans compose.yaml fournissent les valeurs à remplacer. Les autres variables présentes dans .env ne sont pas automatiquement injectées dans les conteneurs.

La forme ${DB_NAME:-wordpress} fournit une valeur par défaut si la variable est absente ou vide.
La forme ${DB_NAME:?Définir DB_NAME} demande une valeur non vide et signale une erreur sinon.

Choisir un autre fichier pour l’interpolation

Par défaut, Compose utilise le fichier .env.
Pour utiliser, par exemple, .env.production, on le sélectionne avec l’option --env-file :

docker compose --env-file ./.env.production up

Le comportement de l’interpolation reste identique.

4. Fournir les variables avec env_file

Déclarer env_file sous un service permet de fournir au conteneur les variables contenues dans un fichier :

services:
  app:
    env_file:
      - ./app.env

Le fichier app.env contient des lignes de la forme NOM=valeur, par exemple WORDPRESS_DB_NAME=wordpress.
Compose transmet TOUTES ces variables au conteneur app.

L’interpolation et env_file sont des possibilités complémentaires ; notre YAML final utilise directement environment et secrets.

7.8 Dépendances et disponibilité des services

Démarré ne signifie pas prêt : une base de données peut avoir lancé son processus sans encore accepter les connexions applicatives.

1. Exprimer les dépendances de démarrage

services:
  web:
    depends_on:
      - app

  app:
    depends_on:
      db:
        condition: service_healthy

1. Pour web, la forme simple demande que app soit démarré avant lui. Elle ne vérifie pas que WordPress est prêt à répondre.
2. Pour app, la forme détaillée avec condition: service_healthy attend que le contrôle de santé de db indique un état sain avant son démarrage.

2. Définir le contrôle de santé de MariaDB

services:
  db:
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 10

Ces dépendances organisent le démarrage. Après celui-ci, une application robuste doit aussi gérer les indisponibilités et les reconnexions : depends_on ne remplace pas ce comportement applicatif.

7.9 Cycle de vie et portée de Compose

Une fois les services et leurs ressources décrits, Compose permet de gérer leur cycle de vie comme un projet. Dans notre scénario, cela concerne web, app, db, leurs réseaux et leurs volumes.

Compose est couramment utilisé au moyen de la commande docker compose (plugin Compose moderne). Il interagit avec Docker Engine et gère les ressources du projet.

La forme historique docker-compose (avec trait d'union) se rencontre encore dans d'anciens supports ; la syntaxe moderne est docker compose.

La déclaration Compose décrit l'application.
Docker Engine reste chargé de l'exécution effective des conteneurs sur l'hôte ciblé.

7.10 Compose et Kubernetes : deux niveaux différents

Notre fichier décrit une application cohérente sur un hôte Docker. Cela ne lui apporte pas automatiquement les capacités d’un orchestrateur de cluster.

Compose et Kubernetes utilisent tous deux des descriptions déclaratives, mais ils ne répondent pas au même besoin opérationnel.

Compose ne constitue pas, à lui seul, un orchestrateur de cluster comparable à Kubernetes. Le fait de décrire plusieurs conteneurs dans un fichier YAML ne suffit pas à fournir les mêmes mécanismes de disponibilité, de placement et de reprise.

7.11 Scénario : NGINX, WordPress et MariaDB

1. Architecture

Reprenons notre architecture du chapitre 5, section 5.2.4 — Règles de communication et sécurisation : un serveur web sur le réseau frontend, une application connectée aux deux réseaux, et une base de données accessible uniquement sur backend.

Lecture de l’architecture :

• Le client atteint web via localhost:8080 sur l’hôte.
• NGINX transmet à app:80 sur frontend.
• WordPress contacte MariaDB via db:3306 sur backend.
• Le conteneur db n’est ni connecté à frontend, ni publié sur l’hôte.

2. Le fichier de configuration

Afin de déclarer cette architecture avec Docker Compose, nous pourrions utiliser le fichier compose.yaml suivant :

services:
  web:
    image: nginx:stable-alpine
    ports:
      - "8080:80"
    volumes:
      # Bind mount : fichier de configuration NGINX fourni par l'hôte
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
    networks:
      - frontend
    depends_on:
      - app

  app:
    image: wordpress:php8.3-apache
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password
    volumes:
      # Volume nommé : conservation des fichiers WordPress
      - wordpress_data:/var/www/html
    networks:
      - frontend
      - backend
    depends_on:
      db:
        condition: service_healthy

  db:
    image: mariadb:11.4
    environment:
      MARIADB_DATABASE: wordpress
      MARIADB_USER: wordpress
      MARIADB_PASSWORD_FILE: /run/secrets/db_password
      MARIADB_ROOT_PASSWORD_FILE: /run/secrets/db_root_password
    secrets:
      - db_password
      - db_root_password
    volumes:
      # Volume Docker : persistance des données MariaDB
      - db_data:/var/lib/mysql
    networks:
      - backend
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 10

networks:
  frontend:
  backend:

volumes:
  wordpress_data:
  db_data:

secrets:
  db_password:
    file: ./secrets/db_password.txt
  db_root_password:
    file: ./secrets/db_root_password.txt

3. Services et communications

Le fichier déclare trois services. Leurs réseaux et leurs ports déterminent les communications possibles.

Les noms app et db servent d’adresses sur les réseaux partagés. Les ports 80 et 3306 sont les ports internes des services, indépendamment du port publié pour NGINX.

Pour approfondir : 7.5 — Réseaux et communication entre services.

4. Configuration et données persistantes

Les trois montages répondent à deux besoins : fournir une configuration depuis l’hôte et conserver les données de l’application.

Le fichier default.conf doit contenir la configuration NGINX qui transmet les requêtes à app:80.
Compose rend ce fichier accessible au conteneur ; le montage seul ne configure pas le reverse proxy.

Les volumes nommés sont déclarés au niveau racine puis référencés sous les services. Ils conservent les données lors du remplacement des conteneurs, tant que les volumes eux-mêmes ne sont pas supprimés.

Pour approfondir : 7.6 — Volumes et persistance des données.

5. Paramètres et accès aux secrets

Les paramètres ordinaires sont transmis avec environment. Les mots de passe sont fournis dans des fichiers secrets accessibles uniquement aux services auxquels ils sont attribués.

Les fichiers secrets ne sont pas créés par cette déclaration : ils doivent exister sur l’hôte et rester protégés. Les variables _FILE sont reconnues par les images utilisées dans ce scénario.

Pour approfondir : 7.7 — Configuration, variables et secrets.

6. Ordre de démarrage et disponibilité

Les deux déclarations depends_on n’apportent pas la même garantie.

Une base déclarée saine ne garantit donc pas que tout le site est prêt. Ces dépendances de démarrage ne constituent pas une surveillance continue capable de rétablir automatiquement toute l’application.

Pour approfondir : 7.8 — Dépendances et disponibilité des services.

7.12 Ce qu’il faut retenir

1. Compose et projet

Le fichier compose.yaml décrit la configuration attendue d’une application multi-services

Un projet regroupe ses services et ses ressources.
Docker Engine exécute les conteneurs.

2. Service et conteneur

Un service est une définition
Un conteneur en est une instance.

image désigne l’image à utiliser
build décrit sa construction.

3. Structure

services décrit les composants.

Les réseaux, volumes et secrets déclarés au niveau racine sont référencés par les services qui les utilisent.

4. Réseaux et ports

Les services partageant un réseau peuvent communiquer par leur nom de service et leur port interne.
ports publie un port sur l’hôte

Un service peut appartenir à plusieurs réseaux.

5. Stockage

Un bind mount rend un fichier ou dossier de l’hôte accessible au conteneur
Un volume nommé conserve des données indépendamment du conteneur.

⚠️ La persistance ne remplace pas une sauvegarde.

6. Modes de montage

:ro impose la lecture seule
:rw autorise lecture et écriture au niveau du montage et constitue le mode par défaut.

⚠️ Ces options ne changent pas les permissions des fichiers sur l’hôte.

7. Variables du conteneur

environment les déclare dans le YAML
env_file les fournit depuis un fichier.

Pour une même variable, environment est prioritaire.

8. Interpolation

Compose remplace les expressions ${VARIABLE} à partir de son environnement ou du fichier .env, que --env-file permet de remplacer.

⚠️ Ce fichier n’injecte pas automatiquement toutes ses variables dans les conteneurs.

9. Valeurs attendues

${VARIABLE:-valeur} fournit une valeur par défaut si la variable est absente ou vide
${VARIABLE:?message} exige une valeur non vide.

Les noms des variables du conteneur doivent correspondre à ceux reconnus par l’image ou l’application.

10. Secrets

Ils sont déclarés au niveau racine puis attribués aux services autorisés.
Dans notre scénario, ils sont accessibles sous /run/secrets/

Les variables _FILE indiquent aux images compatibles où les lire.
⚠️ Les fichiers sources sur l’hôte restent à protéger.

11. Démarrage et disponibilité

depends_on exprime les dépendances
healthcheck évalue la santé d’un service.
condition: service_healthy attend un état sain, sans garantir que tout le site est prêt.

12. Cycle de vie

up crée ou actualise et démarre l’application
stop arrête les conteneurs
down supprime les conteneurs et réseaux du projet créés par Compose, sans supprimer les volumes nommés par défaut.

13. Portée

Compose gère une application sur un moteur Docker
Il ne fournit pas à lui seul l’orchestration d’un cluster comparable à Kubernetes.

Documentation officielle : Docker Compose et Compose file reference.