Le fichier docker-compose.yml : Syntaxe et structure

Fondations : le langage YAML et la structure de base

Au coeur de Docker Compose se trouve le fichier de configuration, traditionnellement nommé `docker-compose.yml` ou `docker-compose.yaml`. Ce fichier utilise la syntaxe YAML (YAML Ain't Markup Language), un format de sérialisation de données conçu pour être facilement lisible par les humains. Avant de plonger dans les directives spécifiques à Docker Compose, comprenons les bases de YAML :

• Indentation : YAML utilise l'indentation (espaces, pas de tabulations !) pour définir la structure et l'imbrication. La cohérence de l'indentation est cruciale. Deux espaces sont une convention courante.
• Clé-Valeur : La structure de base est une paire clé-valeur, séparée par deux-points suivis d'un espace (`cle: valeur`).
• Listes/Séquences : Les éléments d'une liste sont préfixés par un tiret et un espace (`- element1`).
• Commentaires : Les commentaires commencent par un croisillon (`#`) et s'étendent jusqu'à la fin de la ligne.

Un fichier `docker-compose.yml` typique est organisé autour de plusieurs clés de haut niveau qui définissent les différents aspects de votre application multi-conteneurs. Les plus importantes sont : `services`, `networks`, `volumes`, `configs` et `secrets`. Historiquement, une clé `version` était obligatoire pour spécifier la version de la syntaxe du fichier Compose, mais elle est maintenant largement considérée comme obsolète et facultative pour les versions récentes de Docker Compose (v2+).

La section `services` : définir les composants de votre application

La section `services` est la plus importante et la plus détaillée du fichier. C'est ici que vous définissez chaque conteneur qui compose votre application. Chaque clé sous `services` représente le nom d'un service (par exemple, `web`, `db`, `api`). Ce nom sera utilisé par Compose pour gérer le conteneur associé et servira également de nom d'hôte DNS pour la communication inter-services sur les réseaux définis par l'utilisateur.

Pour chaque service, vous pouvez spécifier une multitude d'options pour configurer le conteneur correspondant. Voici les plus courantes :

• image: : : Spécifie l'image Docker à utiliser pour ce service. Si l'image n'est pas locale, Compose la téléchargera (pull) depuis le registry configuré (par défaut, Docker Hub).
• build: : Au lieu d'utiliser une image existante, vous pouvez demander à Compose de construire une image localement.
  • context: : Chemin vers le répertoire contenant le Dockerfile et les fichiers nécessaires au build.
  • dockerfile: : Nom du Dockerfile à utiliser (par défaut : `Dockerfile`).
  • args: : Permet de passer des arguments de build au Dockerfile.
  • target: : Pour les builds multi-étapes, spécifie l'étape cible à construire.
• container_name: : Attribue un nom fixe au conteneur. Généralement déconseillé car cela empêche de lancer plusieurs instances du même service (scaling). Laissez Compose générer les noms (__).
• ports: : Mappe les ports entre l'hôte et le conteneur (syntaxe `"HOST:CONTAINER"` ou `"CONTAINER"` pour un port hôte aléatoire). Liste de chaînes de caractères.

  ports:
    - "8080:80"
    - "127.0.0.1:9000:9000"
    - "53/udp"

• volumes: : Monte des volumes ou des bind mounts dans le conteneur. Liste de chaînes de caractères avec différentes syntaxes :
  • Volume nommé : `"nom_volume:/chemin/conteneur:options"` (options : `ro` pour read-only).
  • Bind mount : `"/chemin/hote:/chemin/conteneur:options"`.

  volumes:
    - db_data:/var/lib/postgresql/data
    - ./app:/app:ro
    - /tmp/cache:/tmp/cache

• networks: : Connecte le service à des réseaux spécifiques (définis dans la section `networks` de haut niveau ou réseaux externes). Peut être une liste de noms de réseaux ou un objet pour une configuration plus fine (alias, IP statique).
• environment: : Définit des variables d'environnement dans le conteneur. Peut être une liste (`"VAR=value"`) ou un dictionnaire (`VAR: value`).

  environment:
    - DEBUG=1
    POSTGRES_USER: user
    POSTGRES_PASSWORD: ${DB_PASSWORD} # Utilise la substitution de variable

• env_file: : Charge les variables d'environnement depuis un ou plusieurs fichiers (`.env` par défaut).
• depends_on: : Définit les dépendances de démarrage entre services. Compose démarrera les dépendances avant le service courant. Attention : ne garantit que le *démarrage* du conteneur dépendant, pas que le service à l'intérieur soit prêt. Pour cela, utiliser des healthchecks ou des scripts d'attente.
• restart: : Définit la politique de redémarrage du conteneur (`no`, `always`, `on-failure`, `unless-stopped`).
• command: [, ...] ou command: "cmd arg1" : Surcharge la commande par défaut de l'image (CMD).
• entrypoint: [, ...] ou entrypoint: "cmd arg1" : Surcharge l'entrypoint de l'image.
• healthcheck: : Définit une commande pour vérifier l'état de santé du service. Utile avec `depends_on`.
• secrets: et configs: : Référence des secrets ou configurations définis au niveau supérieur.

La section `networks` : orchestrer la connectivité

Cette section de haut niveau permet de définir les réseaux personnalisés que vos services utiliseront. Si vous ne définissez pas de réseau, Compose en crée un de type `bridge` par défaut pour votre application. Définir explicitement vos réseaux est une bonne pratique pour plus de clarté et de contrôle.

Chaque clé sous `networks` est le nom que vous donnez à votre réseau.

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    ipam:
      driver: default
      config:
        - subnet: 172.28.0.0/16
  # Réseau externe (créé manuellement hors de Compose)
  external_net:
    external: true

Options courantes pour un réseau :

• driver: : Spécifie le pilote réseau (`bridge`, `overlay`, etc.). Par défaut `bridge`.
• driver_opts: : Passe des options spécifiques au pilote.
• ipam: : Permet de configurer la gestion des adresses IP (IPAM) pour ce réseau (driver, subnet, gateway, ip_range).
• external: true : Indique que ce réseau a été créé en dehors de ce fichier Compose (par exemple, via `docker network create`) et que Compose ne doit pas tenter de le créer ou de le supprimer.
• internal: true : Crée un réseau qui n'a pas de connectivité externe (uniquement inter-conteneurs).

Les services peuvent ensuite se connecter à ces réseaux en les référençant dans leur section `networks`.

La section `volumes` : gérer la persistance des données

De manière similaire aux réseaux, la section `volumes` de haut niveau permet de définir des volumes nommés gérés par Docker. Ces volumes peuvent ensuite être montés par un ou plusieurs services.

Chaque clé sous `volumes` est le nom que vous donnez à votre volume.

volumes:
  # Volume simple géré par Docker
  db_data:
    driver: local
  # Volume utilisant un pilote spécifique avec options
  app_cache:
    driver: my_volume_driver
    driver_opts:
      size: "100m"
      type: "ssd"
  # Volume externe (créé manuellement hors de Compose)
  shared_logs:
    external: true

Options courantes pour un volume :

• driver: : Spécifie le pilote de volume (par défaut `local`).
• driver_opts: : Passe des options spécifiques au pilote de volume.
• external: true : Indique que ce volume a été créé en dehors de Compose.
• name: : Spécifie le nom réel du volume sur l'hôte, différent du nom logique utilisé dans le fichier Compose.

Utiliser des volumes nommés définis ici est la méthode recommandée pour la persistance des données (comme les bases de données) car ils sont gérés par Docker, indépendants du chemin de l'hôte et plus faciles à sauvegarder ou migrer.

Sections `configs` et `secrets` : gérer la configuration sensible

Pour gérer les fichiers de configuration et les données sensibles (mots de passe, clés API) de manière plus sécurisée et découplée, Docker Compose propose les sections `configs` et `secrets`.

Les `configs` et `secrets` définis au niveau supérieur peuvent être basés sur un fichier local ou marqués comme externes (gérés par Docker Swarm ou manuellement).

configs:
  nginx_config:
    file: ./nginx.conf # Chemin vers le fichier de config sur l'hôte
  external_config:
    external: true

secrets:
  db_password:
    file: ./db_password.txt # Fichier contenant le mot de passe
  api_key:
    external: true

Ensuite, dans la définition d'un service, vous pouvez monter ces configs ou secrets. Par défaut, ils sont montés en lecture seule dans `/run/secrets/` pour les secrets et `/` pour les configs.

services:
  web:
    image: nginx
    configs:
      - source: nginx_config
        target: /etc/nginx/nginx.conf # Chemin cible dans le conteneur
    secrets:
      - source: api_key
        target: /etc/app/api_key.txt # Peut spécifier une cible différente

L'utilisation de secrets est particulièrement recommandée pour éviter de coder en dur des informations sensibles dans les images ou les variables d'environnement.