---
title: Docker Compose
description: Décrire et lancer une application composée de plusieurs services.
---

## Le problème résolu par Compose

`docker run` lance un conteneur. Une application réelle utilise souvent plusieurs services : frontend, backend, base de données, stockage, serveur de mail et reverse proxy.

Lancer chaque conteneur à la main, dans le bon ordre et avec les bons réseaux, ports et variables, devient vite ingérable.

Docker Compose décrit toute la stack dans un fichier YAML déclaratif et la pilote avec une seule commande :

```bash
docker compose -f docker-compose.dev.yml up
docker compose -f docker-compose.dev.yml down
```

## Anatomie d'un fichier Compose

```yaml
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test:
        - CMD-SHELL
        - pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile.dev
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      POSTGRES_HOST: postgres
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

volumes:
  postgres_data:
```

## Les notions principales

### services

Chaque clé représente un service. Il utilise soit `image:` pour récupérer une image existante, soit `build:` pour construire une image depuis un Dockerfile.

### depends_on et healthcheck

`depends_on` organise le démarrage. Avec `condition: service_healthy`, le backend n'attend pas seulement que le conteneur PostgreSQL existe : il attend que la base soit prête à accepter des connexions.

### environment

Les variables configurent le conteneur. La syntaxe `${VAR}` lit généralement la valeur depuis un fichier `.env`.

### networks et volumes

Les réseaux et volumes sont déclarés une fois, puis associés aux services qui en ont besoin.

## Superposer plusieurs fichiers

Un projet peut séparer les usages :

| Fichier | Usage |
| --- | --- |
| `docker-compose.dev.yml` | Développement avec hot-reload et bind mounts |
| `docker-compose.prod.yml` | Production avec images préconstruites et politique de redémarrage |
| `docker-compose.local-e2e.yml` | Surcharge pour les tests e2e |

Le second fichier surcharge le premier :

```bash
docker compose \
  -f docker-compose.prod.yml \
  -f docker-compose.local-e2e.yml \
  up
```

<Callout title="Compose orchestre, il ne remplace pas les images" type="info">
  Le Dockerfile décrit comment construire une image. Le fichier Compose décrit comment lancer, configurer et relier plusieurs instances d'images.
</Callout>