YAML pour Docker Compose : Patrons de Configuration et Astuces

Docker Compose utilise YAML pour définir des applications multi-conteneurs. Un docker-compose.yml bien structuré fait la différence entre un environnement de développement fluide et des heures de débogage de problèmes de conteneurs. Ce guide couvre les patrons essentiels et les pièges courants.

Structure de Base

services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
    depends_on:
      - api

  api:
    build: ./api
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://db:5432/myapp
    depends_on:
      - db

  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: myapp
      POSTGRES_PASSWORD: secret

volumes:
  pgdata:

Variables d'Environnement

En Ligne

services:
  api:
    environment:
      NODE_ENV: production
      PORT: "3000"
      DEBUG: "false"

Depuis un Fichier

services:
  api:
    env_file:
      - .env
      - .env.local  # Overrides .env values

Substitution de Variables

Référencez les variables d'environnement de l'hôte :

services:
  api:
    image: myapp:${TAG:-latest}  # Default to "latest"
    environment:
      API_KEY: ${API_KEY}  # Required - fails if not set
      LOG_LEVEL: ${LOG_LEVEL:-info}  # Default to "info"

Réseau

Réseaux Personnalisés

services:
  web:
    networks:
      - frontend
  api:
    networks:
      - frontend
      - backend
  db:
    networks:
      - backend

networks:
  frontend:
  backend:
    internal: true  # No external access

Les services sur le même réseau peuvent se joindre mutuellement par nom de service. Le service db n'est accessible que depuis api, pas depuis web.

Mappage de Ports

ports:
  - "8080:80"         # host:container
  - "443:443"
  - "127.0.0.1:3000:3000"  # Bind to localhost only
  - "3000"            # Random host port

Volumes

Volumes Nommés (Persistants)

services:
  db:
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:
    driver: local

Montages Liés (Développement)

services:
  api:
    volumes:
      - ./src:/app/src          # Source code
      - /app/node_modules       # Anonymous volume (prevent override)

Le patron de volume anonyme (/app/node_modules) empêche le montage lié de l'hôte d'écraser les dépendances installées dans le conteneur.

Vérifications de Santé

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

  api:
    depends_on:
      db:
        condition: service_healthy

Cela garantit que api ne démarre qu'après que db ait passé les vérifications de santé — pas juste quand le conteneur démarre.

Champs d'Extension (Patrons DRY)

Utilisez les champs préfixés x- avec les ancres YAML pour réduire la répétition :

x-common: &common
  restart: unless-stopped
  logging:
    driver: json-file
    options:
      max-size: "10m"
      max-file: "3"

x-env: &common-env
  TZ: UTC
  LOG_FORMAT: json

services:
  api:
    <<: *common
    build: ./api
    environment:
      <<: *common-env
      PORT: "3000"

  worker:
    <<: *common
    build: ./worker
    environment:
      <<: *common-env
      QUEUE: default

Pour en savoir plus sur les ancres YAML, consultez notre guide des ancres et alias YAML.

Compose Multi-Étapes

Développement vs Production

# docker-compose.yml (base)
services:
  api:
    build: ./api
    environment:
      DATABASE_URL: postgres://db:5432/myapp

# docker-compose.override.yml (dev - auto-loaded)
services:
  api:
    volumes:
      - ./api/src:/app/src
    environment:
      NODE_ENV: development
      DEBUG: "true"
    ports:
      - "3000:3000"
      - "9229:9229"  # Debug port

# docker-compose.prod.yml
services:
  api:
    environment:
      NODE_ENV: production
    deploy:
      replicas: 3

# Development (auto-loads override)
docker compose up

# Production
docker compose -f docker-compose.yml -f docker-compose.prod.yml up

Pièges Courants

1. Numéros de Port sans Guillemets

# RISKY - YAML interprets 80:80 as a base-60 number
ports:
  - 80:80

# SAFE - always quote
ports:
  - "80:80"

2. Variables d'Environnement Booléennes

# WRONG - YAML converts to boolean
environment:
  DEBUG: true  # Becomes Python True, not string "true"

# CORRECT - quote all env values
environment:
  DEBUG: "true"

3. Timing de depends_on

depends_on n'attend que le démarrage du conteneur, pas qu'il soit prêt :

# Container starts but DB might not be ready
depends_on:
  - db

# Wait for health check
depends_on:
  db:
    condition: service_healthy

Validez vos fichiers Docker Compose avec notre Validateur YAML.

FAQ

Quelle est la différence entre docker-compose.yml et compose.yml ?

Les deux noms de fichier fonctionnent. compose.yml est la nouvelle convention recommandée par Docker. docker-compose.yml est le nom hérité. Docker Compose v2+ cherche les deux, préférant compose.yml si les deux existent. Pour les nouveaux projets, utilisez compose.yml.

Dois-je utiliser Docker Compose en production ?

Docker Compose est excellent pour le développement et les déploiements simples. Pour la production à grande échelle, envisagez Docker Swarm (qui utilise nativement les fichiers Compose) ou Kubernetes. L'avantage de Compose est que votre configuration de développement informe directement la production, réduisant les différences d'environnement.

Ressources Connexes

• Validateur YAML — Validez le YAML de Docker Compose
• Ancres et Alias YAML — Patrons de configuration DRY
• Tutoriel de Syntaxe YAML — Les fondamentaux YAML