Prendre RDV
Lexique · DevOps / Cloud / Data

Docker Compose : définition, fichier compose.yaml et exemple

L'outil qui décrit une application de plusieurs conteneurs dans un seul fichier et la lance en une commande : services, réseaux, volumes, variables, profils, exemple complet et comparaison avec Kubernetes.

Par Équipe Blent· Mis à jour le · 14 min de lecture· Niveau débutant

Docker Compose en bref

Type
Outil de définition d'applications multi-conteneurs
Éditeur
Docker Inc.
Origine
Fig (Orchard), racheté par Docker en 2014
Fichier
compose.yaml (ou docker-compose.yml)
Commande
docker compose (v2, plugin de la CLI)
Format
Compose Specification, standard ouvert
Périmètre
Un seul hôte Docker

Définition : Docker Compose

Docker Compose est un outil qui permet de définir et de lancer une application composée de plusieurs conteneurs à partir d'un seul fichier déclaratif, généralement nommé compose.yaml. Ce fichier décrit les services (une API, une base de données, un cache), les réseaux qui les relient, les volumes qui conservent leurs données et leurs variables d'environnement. La commande docker compose up crée alors l'ensemble, dans le bon ordre, sur une machine équipée de Docker. Intégré à la CLI Docker depuis la version 2, Compose est l'outil de référence pour les environnements de développement, les tests d'intégration et les déploiements simples sur un seul serveur.

En une phrase : Docker Compose décrit dans un fichier YAML tous les conteneurs d'une application et les lance ensemble avec une seule commande.

Dans cette définition

Qu'est-ce que Docker Compose ?

Docker Compose répond à un problème très concret. Une application réelle est rarement un seul conteneur : il faut une API, une base de données, un cache, parfois un worker et un reverse proxy. Les lancer un par un avec Docker, en n'oubliant ni le réseau, ni les volumes, ni les variables, devient vite fastidieux et source d'erreurs.

Compose remplace cette suite de commandes par un fichier déclaratif. Vous décrivez l'état voulu de l'application, Compose se charge de créer les ressources dans le bon ordre et de les supprimer proprement. L'outil est né sous le nom de Fig, développé par la start-up Orchard, rachetée par Docker en 2014. Fig est rapidement devenu Docker Compose. La première version, écrite en Python, s'installait séparément sous le nom docker-compose. La version 2, réécrite en Go, est intégrée à la CLI Docker et s'invoque avec docker compose ; depuis 2023, elle est la seule maintenue. Le format du fichier est désormais un standard ouvert, la Compose Specification.

Compose occupe une place précise : il orchestre plusieurs conteneurs, mais sur une seule machine. C'est l'outil idéal pour le développement, les tests et les déploiements simples. Pour répartir des conteneurs sur un cluster, assurer la haute disponibilité et l'autoscaling, on passe à Kubernetes.

À retenir : Docker construit et lance un conteneur, Docker Compose lance une application de plusieurs conteneurs sur une machine, Kubernetes orchestre des conteneurs sur un cluster.

Comment fonctionne Docker Compose ?

Compose traduit un fichier déclaratif en une série d'opérations Docker, qu'il exécute dans le bon ordre et qu'il sait défaire.

  1. Décrire l'application

    Le fichier compose.yaml liste les services, chacun avec son image ou son contexte de build, ses ports, ses variables, ses volumes et ses dépendances.

  2. Créer les ressources partagées

    À l'exécution de docker compose up, Compose crée un réseau dédié au projet et les volumes nommés déclarés, préfixés par le nom du projet.

  3. Construire ou tirer les images

    Les services avec une section build sont construits localement ; les autres images sont téléchargées depuis leur registre.

  4. Démarrer dans l'ordre

    Les conteneurs sont lancés en respectant depends_on. Avec une condition service_healthy, Compose attend qu'un service réponde à son healthcheck avant de démarrer ceux qui en dépendent.

  5. Relier les services

    Sur le réseau du projet, chaque service est joignable par son nom : l'API contacte la base à l'adresse db:5432, sans adresse IP à gérer.

  6. Exploiter puis tout arrêter

    docker compose logs, ps et exec servent au suivi ; docker compose down supprime conteneurs et réseau, et l'option -v supprime aussi les volumes.

Anatomie d'un fichier compose.yaml

Un fichier Compose s'organise autour de quelques sections de premier niveau.

  • services : le cœur du fichier. Chaque service correspond à un conteneur (ou à plusieurs répliques) avec son image ou son build, ses ports, sa command, ses volumes, son healthcheck et sa politique restart.
  • networks : par défaut, Compose crée un réseau unique pour le projet, sur lequel chaque service est joignable par son nom. Déclarer plusieurs réseaux permet d'isoler des groupes de services, par exemple un réseau public pour le reverse proxy et un réseau interne pour la base.
  • volumes : les volumes nommés conservent les données au-delà de la vie des conteneurs. Un montage de répertoire (./src:/app/src) sert plutôt en développement, pour voir le code modifié sans reconstruire l'image.
  • Variables d'environnement : environment les déclare directement, env_file les charge depuis un fichier, et les références ${VARIABLE} sont remplacées à partir du shell ou d'un fichier .env.
  • profiles : rendent un service optionnel, activé seulement à la demande.
  • secrets et configs : montent des fichiers sensibles ou de configuration dans les conteneurs, sans les intégrer aux images.

Plusieurs fichiers peuvent se combiner : compose.override.yaml est fusionné automatiquement, et l'option -f permet d'empiler par exemple un compose.prod.yaml au-dessus du fichier de base.

Exemple : une API avec PostgreSQL et Redis

Cette stack lance une API construite à partir du Dockerfile du projet, une base PostgreSQL dont les données sont conservées dans un volume, un cache Redis et, à la demande, une interface d'administration de la base.

yaml
services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://app:${POSTGRES_PASSWORD}@db:5432/app
      REDIS_URL: redis://cache:6379/0
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    restart: unless-stopped

  db:
    image: postgres:17
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 5s
      timeout: 3s
      retries: 10

  cache:
    image: redis:7-alpine
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - redisdata:/data

  adminer:
    image: adminer
    ports:
      - "8080:8080"
    profiles: ["debug"]

volumes:
  pgdata:
  redisdata:

Plusieurs points méritent l'attention. L'API joint la base à l'adresse db et le cache à l'adresse cache : ce sont les noms des services. Seuls l'API et Adminer publient un port sur l'hôte ; la base et le cache restent accessibles uniquement depuis le réseau du projet. Grâce au healthcheck et à condition: service_healthy, l'API ne démarre que lorsque PostgreSQL accepte réellement les connexions. Enfin, le mot de passe n'est pas écrit dans le fichier : il vient d'un fichier .env, exclu du dépôt Git.

bash
# Le mot de passe est lu depuis .env, à ne jamais versionner
echo "POSTGRES_PASSWORD=change-moi" > .env

# Construire l'image de l'API et lancer la stack en arrière-plan
docker compose up -d --build

# Suivre l'état et les journaux
docker compose ps
docker compose logs -f api

# Ouvrir un client SQL dans le conteneur de la base
docker compose exec db psql -U app -d app

# Lancer aussi les services du profil debug (Adminer)
docker compose --profile debug up -d

# Tout arrêter en conservant les volumes
docker compose down

# Ou tout supprimer, volumes et données compris
docker compose down -v

En développement, docker compose watch peut en plus synchroniser les fichiers modifiés ou reconstruire un service automatiquement à chaque changement. Pour aller plus loin sur la syntaxe, consultez notre article Docker Compose : tout savoir.

À quoi sert Docker Compose ?

Compose excelle partout où une application de quelques services doit être lancée vite, à l'identique, sur une seule machine.

  • Environnement de développement

    Lancer l'application et toutes ses dépendances (base, cache, file de messages) en une commande, pour chaque développeur.

  • Tests d'intégration

    Monter dans un pipeline CI un environnement complet et éphémère, puis le détruire après les tests.

  • Démonstrations et formations

    Distribuer une stack complète, prête à démarrer, dans un dépôt Git.

  • Petits déploiements

    Héberger une application interne ou un outil auto-hébergé sur un serveur unique.

  • Essayer un logiciel

    Tester une stack d'observabilité, un outil de BI ou une base vectorielle à partir du fichier fourni par l'éditeur.

  • Prototypes de microservices

    Valider le découpage et les échanges entre services avant de passer à un orchestrateur.

Quels sont les avantages de Docker Compose ?

Compose transforme une liste de commandes docker run fragiles en un fichier versionné, lisible et partagé par toute l'équipe.

  • Toute l'application décrite dans un seul fichier YAML, versionné avec le code.
  • Une seule commande pour démarrer, reconstruire ou arrêter l'ensemble.
  • Un réseau et une résolution DNS par nom de service créés automatiquement.
  • Gestion de l'ordre de démarrage et des healthchecks entre services.
  • Profils, fichiers de surcharge et interpolation de variables pour adapter un même fichier à plusieurs contextes.
  • Prise en main rapide, sans cluster ni infrastructure supplémentaire.

Quelles sont les limites de Docker Compose ?

Compose a été pensé pour une machine. Ses limites apparaissent dès que la production exige résilience et mise à l'échelle.

  • Un seul hôte : pas de répartition des conteneurs sur plusieurs serveurs.
  • Pas de haute disponibilité : si la machine tombe, toute l'application tombe.
  • Mise à l'échelle manuelle et limitée, sans autoscaling.
  • Mises à jour sans interruption difficiles à obtenir sans outillage complémentaire.
  • Gestion des secrets rudimentaire comparée à un orchestrateur ou à un coffre-fort dédié.

Docker Compose vs Kubernetes : quelles différences ?

Les deux outils décrivent des applications multi-conteneurs de façon déclarative, mais ils ne jouent pas dans la même catégorie.

CritèreDocker ComposeKubernetes
PérimètreUne seule machineUn cluster de plusieurs nœuds
DescriptionUn fichier compose.yamlPlusieurs manifestes (Deployment, Service, Ingress…)
Haute disponibilitéNon : la machine est un point unique de défaillanceOui : redémarrage et replanification automatiques
Mise à l'échelleManuelle, sur la même machineManuelle ou automatique, sur tout le cluster
Mises à jourRecréation des conteneursRolling updates, retour arrière intégré
RéseauRéseau du projet et DNS par nom de serviceServices, Ingress, politiques réseau
Courbe d'apprentissageQuelques heuresPlusieurs semaines
Idéal pourDéveloppement, tests, petits déploiementsProduction à grande échelle, plateformes partagées

Beaucoup d'équipes utilisent les deux : Compose sur le poste du développeur et dans les tests d'intégration du pipeline CI/CD, Kubernetes en production. Les images, elles, restent identiques. Pour faire vos premiers pas sur un cluster, suivez notre tutoriel Kubernetes.

Quand utiliser Docker Compose ?

Le critère déterminant est le nombre de machines et le niveau de disponibilité attendu.

Pertinent si

Compose suffit

  • L'application compte quelques services sur une seule machine.
  • Vous voulez un environnement de développement reproductible.
  • Un pipeline CI doit lancer des tests d'intégration complets.
  • Une courte interruption lors des mises à jour est acceptable.
Moins adapté si

Passez à un orchestrateur

  • L'application doit survivre à la panne d'un serveur.
  • La charge varie et exige une mise à l'échelle automatique.
  • Des dizaines de services sont gérés par plusieurs équipes.
  • Les déploiements doivent être progressifs et sans interruption.

Outils associés à Docker Compose

Compose s'insère entre Docker, qu'il pilote, et les orchestrateurs, vers lesquels on migre quand l'application grandit.

Les concepts à connaître autour de Docker Compose

Ces notions permettent de situer Compose dans une chaîne de livraison moderne.

Ressources pour approfondir Docker Compose

Trois articles du blog Blent pour maîtriser Compose et préparer la suite.

Questions fréquentes

Questions fréquentes

docker-compose, avec un tiret, est la première version de l'outil, écrite en Python et installée séparément. docker compose, avec un espace, est la version 2, réécrite en Go et intégrée à la CLI Docker comme plugin. La v1 n'est plus maintenue depuis 2023 : utilisez docker compose.

Expertise

À propos de l'auteur

Équipe Blent

Les ingénieurs et mentors Blent conçoivent, automatisent et mettent en production des infrastructures Cloud, et forment chaque année des centaines de professionnels au DevOps.

Sources et méthodologie

  • Documentation officielle Docker Compose et Compose Specification (compose-spec.io)
  • Documentation Kompose
  • Retours d'expérience des projets et formations Blent
Lexique

Explorer le lexique

Voir toutes les définitions