# Docker Compose

Docker Compose décrit dans un seul fichier une application faite de plusieurs conteneurs : lesquels, sur quels ports, avec quelles données, reliés comment. Une commande les démarre tous, une autre les arrête.

Ce cours suppose d'avoir suivi [Docker](/virtualisation/docker).

## Le problème

L'[API des scores](/reseau/api) garde ses scores dans une liste en mémoire : ils disparaissent à chaque redémarrage. Il lui faut une base de données, donc un deuxième programme, donc un deuxième conteneur.

Avec `docker run`, cela donne deux longues commandes à taper dans le bon ordre, un réseau à créer pour que les conteneurs se voient, un volume à ne pas oublier. Personne ne retient ces lignes, et le collègue qui arrive sur le projet ne les connaît pas.

Compose remplace ces commandes par un fichier, rangé dans Git avec le code.

## La notion

| Mot | Sens |
| --- | --- |
| Service | Un conteneur décrit dans le fichier, avec son image et ses réglages |
| `compose.yaml` | Le fichier de description. L'ancien nom `docker-compose.yml` est encore accepté |
| Projet | L'ensemble des services d'un même fichier |
| Réseau | Créé automatiquement : tous les services du projet s'y voient |
| Volume | Un espace de stockage qui survit aux conteneurs |

La commande s'écrit aujourd'hui `docker compose`, avec une espace. L'ancienne forme `docker-compose`, avec un tiret, était un outil séparé.

### Le format YAML

Le fichier est en YAML : un format de données, comme JSON, où la structure est donnée par **l'indentation**.

```yaml
services:
  api:
    ports:
      - "8000:8000"
```

| Écriture | Sens |
| --- | --- |
| `clé: valeur` | Une entrée de dictionnaire |
| Un niveau d'indentation de plus | Un dictionnaire dans le précédent |
| `- élément` | Un élément de liste |

Deux espaces par niveau, jamais de tabulation. Une indentation fausse est la première cause d'erreur.

## L'architecture visée

<Mermaid
  chart={`flowchart LR
    jeu[Le jeu ou curl<br/>sur l'hôte]
    subgraph projet [Réseau du projet Compose]
      api[Service api<br/>FastAPI, port 8000]
      db[(Service db<br/>Redis, port 6379)]
    end
    vol[(Volume<br/>scores-data)]
    jeu -- "localhost:8000" --> api
    api -- "db:6379" --> db
    db --- vol`}
/>

Seul le port de l'API est ouvert sur l'hôte. La base de données n'est joignable que par les autres services : rien ne l'expose à l'extérieur.

La base choisie est [Redis](https://redis.io). Elle offre une structure faite pour les classements, l'**ensemble trié** : chaque élément a un score, et la base les garde dans l'ordre.

## Adapter l'API

```text
server/
├── compose.yaml
├── Dockerfile
├── main.py
└── requirements.txt
```

Une dépendance de plus dans `requirements.txt` :

```text
fastapi==0.115.6
uvicorn==0.34.0
redis==5.2.1
```

Et `main.py` remplace sa liste par la base :

```python
# server/main.py
import os

import redis
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(title="Scores BestGameOfTheYear")

db = redis.Redis(host=os.environ["REDIS_HOST"], decode_responses=True)


class Score(BaseModel):
    player: str
    turns: int


@app.get("/scores")
def list_scores():
    best = db.zrange("scores", 0, 9, withscores=True)
    return [{"player": player, "turns": int(turns)} for player, turns in best]


@app.post("/scores", status_code=201)
def add_score(score: Score):
    db.zadd("scores", {score.player: score.turns})
    return {"player": score.player, "turns": score.turns}
```

Ce qui a changé :

- `zadd` range un joueur dans l'ensemble trié `scores`, avec son nombre de tours.
- `zrange("scores", 0, 9)` rend les dix premiers, du plus petit nombre de tours au plus grand. Le tri n'est plus fait en Python.
- L'adresse de la base vient d'une **variable d'environnement**, `REDIS_HOST`. Le code ne sait pas où est la base : c'est la configuration qui le lui dit.

Le contrat de l'API n'a pas changé : mêmes routes, mêmes réponses. Le jeu n'a rien à modifier.

:::note{title="Un score par joueur"}

Dans un ensemble trié, chaque élément est unique. Un joueur qui envoie un nouveau score remplace l'ancien, même s'il est moins bon. Garder le meilleur est l'un des exercices.

:::

Le `Dockerfile` reste celui du cours précédent.

## Écrire le fichier compose.yaml

```yaml
services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      REDIS_HOST: db
    depends_on:
      - db

  db:
    image: redis:7-alpine
    command: redis-server --appendonly yes
    volumes:
      - scores-data:/data

volumes:
  scores-data:
```

| Clé | Rôle | Équivalent `docker run` |
| --- | --- | --- |
| `build: .` | Construit l'image à partir du `Dockerfile` du dossier | `docker build` |
| `image:` | Utilise une image existante | Le nom de l'image |
| `ports:` | Ouvre un port, hôte puis conteneur | `-p` |
| `environment:` | Définit des variables d'environnement | `-e` |
| `volumes:` | Branche un volume sur un dossier du conteneur | `-v` |
| `command:` | Remplace la commande de démarrage de l'image | La fin de la ligne |
| `depends_on:` | Démarre `db` avant `api` | Lancer dans le bon ordre |

La ligne `command` demande à Redis d'écrire chaque modification sur disque, dans `/data`. Ce dossier est branché sur le volume `scores-data`, déclaré en bas du fichier.

### Les services se trouvent par leur nom

C'est le point central. Sur le réseau du projet, **le nom d'un service est son adresse**. L'API joint la base à l'adresse `db`, parce que le service s'appelle `db`.

D'où `REDIS_HOST: db`. Écrire `localhost` ne marcherait pas : dans le conteneur `api`, `localhost` désigne le conteneur `api` lui-même.

## Démarrer et utiliser

```bash
cd server
docker compose up -d --build
```

`up` crée le réseau, le volume et les conteneurs. `-d` rend la main, `--build` reconstruit l'image de l'API si le code a changé.

```bash
docker compose ps
```

La sortie, réduite ici à ses colonnes utiles :

```text
SERVICE   STATE     PORTS
api       running   0.0.0.0:8000->8000/tcp
db        running   6379/tcp
```

Le port de `db` n'a pas de flèche : il n'est pas ouvert sur l'hôte.

```bash
curl -X POST http://localhost:8000/scores \
  -H "Content-Type: application/json" \
  -d '{"player": "Alice", "turns": 42}'

curl -X POST http://localhost:8000/scores \
  -H "Content-Type: application/json" \
  -d '{"player": "Bob", "turns": 30}'

curl http://localhost:8000/scores
```

```json
[{"player":"Bob","turns":30},{"player":"Alice","turns":42}]
```

### Vérifier que les scores survivent

```bash
docker compose down      # supprime les conteneurs et le réseau
docker compose up -d     # en recrée de nouveaux
curl http://localhost:8000/scores
```

```json
[{"player":"Bob","turns":30},{"player":"Alice","turns":42}]
```

Les conteneurs sont neufs, les scores sont toujours là : ils étaient dans le volume.

## Les commandes du quotidien

| Commande | Effet |
| --- | --- |
| `docker compose up -d` | Démarre tout |
| `docker compose up -d --build` | Reconstruit les images, puis démarre |
| `docker compose ps` | L'état des services |
| `docker compose logs -f api` | Suit les journaux d'un service |
| `docker compose exec api bash` | Ouvre un terminal dans un service |
| `docker compose restart api` | Redémarre un service |
| `docker compose stop` | Arrête sans supprimer |
| `docker compose down` | Supprime conteneurs et réseau, **garde** les volumes |
| `docker compose down -v` | Supprime aussi les volumes |

:::danger{title="down -v efface les données"}

L'option `-v` supprime les volumes, donc la base de données. Elle est utile pour repartir de zéro en développement, et irréversible partout ailleurs.

:::

## Les secrets et la configuration

Ce qui change d'une machine à l'autre, et tout ce qui est secret, ne s'écrit pas dans `compose.yaml`. Compose lit un fichier `.env` placé à côté de lui.

```text
API_PORT=8000
```

```yaml
    ports:
      - "${API_PORT}:8000"
```

Le fichier `.env` reste hors de Git. Le `.gitignore` du projet l'exclut déjà, et autorise un `.env.example` qui montre les variables attendues, sans leurs valeurs.

## Les erreurs fréquentes

| Message ou symptôme | Cause | Solution |
| --- | --- | --- |
| Erreur de lecture du fichier YAML | Indentation, tabulation | Deux espaces par niveau |
| `port is already allocated` | Le port de l'hôte est pris | Changer le premier nombre de `ports` |
| L'API répond `500` | Elle n'arrive pas à joindre la base | `docker compose logs api`, vérifier `REDIS_HOST` |
| `KeyError: 'REDIS_HOST'` au démarrage | Variable d'environnement absente | Vérifier `environment:` |
| Le code modifié n'est pas pris en compte | Image non reconstruite | `docker compose up -d --build` |

`depends_on` garantit l'ordre de **démarrage**, pas que la base soit prête à répondre. Redis démarre en une fraction de seconde, donc cela ne se voit pas ici. Avec une base plus lente, on ajoute un contrôle d'état, `healthcheck`, au service de la base.

## À retenir

- Un fichier `compose.yaml` décrit tous les conteneurs d'une application.
- `docker compose up -d` démarre tout, `docker compose down` supprime tout sauf les volumes.
- Entre services, l'adresse est le nom du service.
- La configuration passe par des variables d'environnement, les secrets par un fichier `.env` hors de Git.
- Les données vivent dans un volume.

## Exercices

1. Mettre en place les deux services, ajouter trois scores, puis vérifier qu'ils survivent à `docker compose down` suivi de `up`.
2. Recommencer avec `docker compose down -v`. Que constate-t-on ?
3. Remplacer `REDIS_HOST: db` par `REDIS_HOST: localhost`, relancer, appeler l'API et lire ses journaux. Expliquer l'erreur.
4. Ouvrir un terminal dans le service `db` avec `docker compose exec db redis-cli`, et afficher l'ensemble trié avec `ZRANGE scores 0 -1 WITHSCORES`.
5. Modifier `add_score` pour ne remplacer le score d'un joueur que s'il est meilleur. L'option `lt` de `zadd` aide.
6. Rendre le port de l'hôte configurable par un fichier `.env`, et ajouter un `.env.example`.
