feat: docs

content/docs/orchestration/docker-compose.mdx

@@ -0,0 +1,94 @@
+---
+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>