Aide-mémoire Docker Compose (2026) : clés de service

Vue d’ensemble

Docker Compose définit les applications multi-conteneurs dans un seul fichier YAML. Cet aide-mémoire couvre la structure de compose.yaml, chaque clé de service, les options d’environnement et de configuration, la mise en réseau et les volumes, l’intégralité de la CLI, les fichiers override, et les profiles. Tous les exemples ciblent Docker Compose v2 (le plugin docker compose) et la spécification Compose ; la clé version: héritée est obsolète et ignorée.

Structure compose.yaml

La structure de base d’un fichier Compose :

services:      # Définir les services conteneurisés
volumes:       # Définir les volumes nommés
networks:      # Définir les réseaux personnalisés
configs:       # Définir les configs (pour swarm, optionnel)
secrets:       # Définir les secrets (pour swarm, optionnel)

Services : clés de base

Mise en réseau et ports

Environnement et configuration

Stockage : volumes et bind mounts

Note : Définissez les volumes nommés au niveau supérieur :

volumes:
  my_data:
    driver: local

Limites de ressources

Vérifications de santé

Exemple complet :

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
  interval: 30s
  timeout: 5s
  start_period: 10s
  retries: 3

Dépendances et ordre de démarrage

Attention : condition: service_healthy requiert que le service ait une healthcheck. Sans cela, la condition échoue immédiatement.

Exemple complet :

services:
  web:
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started

Sécurité : secrets et configs

Définition au niveau supérieur :

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

configs:
  nginx_config:
    file: ./nginx.conf

Accès dans le conteneur :

# Dans le shell : cat /run/secrets/db_password

Profiles

Les profiles vous permettent d’inclure des services de manière conditionnelle.

services:
  web:
    image: nginx:latest
    # Toujours inclus

  debug:
    image: busybox:latest
    profiles: [debug]
    # Inclus seulement avec --profile debug

  monitoring:
    image: prom/prometheus:latest
    profiles: [monitoring, prod]
    # Inclus avec --profile monitoring OU --profile prod

Usage :

docker compose up                        # Inclure seulement les services sans profiles
docker compose --profile debug up        # Inclure web + debug
docker compose --profile monitoring up   # Inclure web + monitoring
docker compose --profile debug --profile monitoring up  # Inclure les trois

Réseaux (niveau supérieur)

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.name: br0

Usage dans les services :

services:
  web:
    networks: [frontend, backend]
  db:
    networks: [backend]

Volumes (niveau supérieur)

volumes:
  db_data:
    driver: local
  shared_cache:
    driver: local
    driver_opts:
      type: tmpfs
      device: tmpfs

Fichiers override

Docker Compose charge automatiquement docker-compose.override.yaml et le fusionne avec compose.yaml.

compose.yaml (production) :

services:
  web:
    image: myapp:latest
    environment:
      LOG_LEVEL: warn

docker-compose.override.yaml (développement local) :

services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      LOG_LEVEL: debug

Résultat lors de l’exécution de docker compose up :
– L’image est construite à partir de ./Dockerfile (remplace image: myapp:latest)
– Le port 8000 est exposé sur l’hôte
– LOG_LEVEL est défini sur debug
– Le mapping de port et LOG_LEVEL sont fusionnés

Fichier override explicite :

docker compose -f compose.yaml -f compose.prod.yaml up

Commandes CLI

Patterns à réutiliser

# Développement avec fichier override
# compose.yaml : configuration de production
# docker-compose.override.yaml : ajustements dev locaux

# Base de données avec healthcheck et depends_on
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
  web:
    depends_on:
      db:
        condition: service_healthy

# Application multi-niveaux
services:
  web:
    networks: [frontend, backend]
  cache:
    networks: [backend]
  db:
    networks: [backend]

# Charger l'environnement à partir d'un fichier avec remplacements
services:
  app:
    env_file: .env
    environment:
      LOG_LEVEL: debug  # Remplacer depuis .env

# Profiles pour les services optionnels
  monitoring:
    profiles: [monitoring]
  debug:
    profiles: [debug]

# Utiliser compose watch pour le rechargement en direct (Compose 2.22+)
# docker compose watch
watch:
  - path: ./src
    action: sync
    target: /app/src
  - path: ./requirements.txt
    action: rebuild

FAQ

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

Les deux sont supportés. Docker préfère compose.yaml (sans tiret). Les deux sont équivalents ; choisissez une convention et tenez-vous-y. La documentation moderne utilise compose.yaml.

Comment définir des variables d’environnement dans Docker Compose ?

Utilisez la clé environment dans un service, ou chargez à partir d’un fichier avec env_file: .env. Les variables peuvent être codées en dur, à partir du shell hôte (${VAR_NAME}), ou à partir de fichiers .env. Utilisez les secrets pour les valeurs sensibles.

Comment m’assurer qu’un service démarre avant un autre ?

Utilisez depends_on: db: condition: service_healthy (requiert une HEALTHCHECK). Pour juste l’ordre de démarrage sans validation, utilisez la forme courte depends_on: [db] ; elle ordonne seulement le démarrage et n’attend pas la préparation.

Comment utiliser les fichiers override Docker Compose ?

Créez docker-compose.override.yaml dans le même répertoire. Compose le charge automatiquement et le fusionne avec compose.yaml. Remplacez des services spécifiques sans éditer le fichier principal. Utile pour le développement local vs. la production.

Que sont les profiles Docker Compose ?

Les profiles vous permettent d’inclure des services de manière conditionnelle. Définissez profiles: [debug] sur un service, puis utilisez docker compose --profile debug up pour l’inclure. Utile pour les services de débogage optionnels ou les piles de monitoring.