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
| 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- 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-, 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
| É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
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
Une dépendance de plus dans requirements. :
Code
Et main.py remplace sa liste par la base :
Python
Ce qui a changé :
zaddrange 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.
Le Dockerfile reste celui du cours précédent.
Écrire le fichier compose.yaml
YAML
| 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_. Écrire localhost ne marcherait pas : dans le conteneur api, localhost désigne le conteneur api lui-même.
Démarrer et utiliser
Bash
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
La sortie, réduite ici à ses colonnes utiles :
Code
Le port de db n'a pas de flèche : il n'est pas ouvert sur l'hôte.
Bash
JSON
Vérifier que les scores survivent
Bash
JSON
Les conteneurs sont neufs, les scores sont toujours là : ils étaient dans le volume.
Les commandes du quotidien
| Commande | Effet |
|---|---|
docker compose up - | Démarre tout |
docker compose up - | Reconstruit les images, puis démarre |
docker compose ps | L'état des services |
docker compose logs - | 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 - | Supprime aussi les volumes |
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
YAML
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: 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 - |
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.yamldécrit tous les conteneurs d'une application. docker compose up -démarre tout,d docker compose downsupprime 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
.envhors de Git. - Les données vivent dans un volume.
Exercices
- Mettre en place les deux services, ajouter trois scores, puis vérifier qu'ils survivent à
docker compose downsuivi deup. - Recommencer avec
docker compose down -. Que constate-t-on ?v - Remplacer
REDIS_parHOST: db REDIS_, relancer, appeler l'API et lire ses journaux. Expliquer l'erreur.HOST: localhost - Ouvrir un terminal dans le service
dbavecdocker compose exec db redis-, et afficher l'ensemble trié aveccli ZRANGE scores 0 -.1 WITHSCORES - Modifier
add_scorepour ne remplacer le score d'un joueur que s'il est meilleur. L'optionltdezaddaide. - Rendre le port de l'hôte configurable par un fichier
.env, et ajouter un.env.example.