Aller au contenu

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.

Le problème

L'API des scores 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

MotSens
ServiceUn conteneur décrit dans le fichier, avec son image et ses réglages
compose.yamlLe fichier de description. L'ancien nom docker-compose.yml est encore accepté
ProjetL'ensemble des services d'un même fichier
RéseauCréé automatiquement : tous les services du projet s'y voient
VolumeUn 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.

YAMLYAML
services: api: ports: - "8000:8000"
ÉcritureSens
clé: valeurUne entrée de dictionnaire
Un niveau d'indentation de plusUn dictionnaire dans le précédent
- élémentUn é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

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. 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

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

Une dépendance de plus dans requirements.txt :

Code
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.

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

YAMLYAML
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 dossierdocker build
image:Utilise une image existanteLe 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'imageLa fin de la ligne
depends_on:Démarre db avant apiLancer 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

TerminalBash
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é.

TerminalBash
docker compose ps

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

Code
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.

TerminalBash
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
JSONJSON
[{"player":"Bob","turns":30},{"player":"Alice","turns":42}]

Vérifier que les scores survivent

TerminalBash
docker compose down # supprime les conteneurs et le réseau docker compose up -d # en recrée de nouveaux curl http://localhost:8000/scores
JSONJSON
[{"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

CommandeEffet
docker compose up -dDémarre tout
docker compose up -d --buildReconstruit les images, puis démarre
docker compose psL'état des services
docker compose logs -f apiSuit les journaux d'un service
docker compose exec api bashOuvre un terminal dans un service
docker compose restart apiRedémarre un service
docker compose stopArrête sans supprimer
docker compose downSupprime conteneurs et réseau, garde les volumes
docker compose down -vSupprime aussi les volumes
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.

Code
API_PORT=8000
YAMLYAML
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ômeCauseSolution
Erreur de lecture du fichier YAMLIndentation, tabulationDeux espaces par niveau
port is already allocatedLe port de l'hôte est prisChanger le premier nombre de ports
L'API répond 500Elle n'arrive pas à joindre la basedocker compose logs api, vérifier REDIS_HOST
KeyError: 'REDIS_HOST' au démarrageVariable d'environnement absenteVérifier environment:
Le code modifié n'est pas pris en compteImage non reconstruitedocker 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.