00. Docker Compose, le point de départ

Une commande#

cp .env.template .env
docker compose up --build        # → http://localhost:8000/docs

Pour faire tourner l’API sur l’hôte, démarrer aussi RabbitMQ : le lifespan de l’API s’y connecte. Appliquer d’abord les migrations en connexion directe via le service migrate :

cp .env.template .env           # une seule fois ; adapter les valeurs
docker compose up -d postgres pgbouncer valkey rabbitmq mailpit
docker compose run --rm migrate
cd backend
uv sync
make run

Le vrai sujet : l'ordre de démarrage#

Onze conteneurs qui démarrent en même temps, c'est onze façons d'échouer. L'API qui se connecte à une base pas encore prête, le worker qui déclare une file sur un broker en cours d'initialisation, les migrations qui partent avant que PostgreSQL n'accepte les connexions.

La réponse tient en deux mécanismes qui n'ont d'intérêt qu'ensemble.

1. Les healthchecks : « prêt » plutôt que « démarré »#

postgres:
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
    interval: 10s
    retries: 5

rabbitmq:
  healthcheck:
    test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
    interval: 15s
    retries: 5

valkey:
  healthcheck:
    test: ["CMD", "valkey-cli", "ping"]

Ces sondes ont une portée limitée : pg_isready vérifie l’acceptation des connexions, pas le schéma ni les droits applicatifs ; rabbitmq-diagnostics ping vérifie le processus Erlang et ne prouve pas qu’une file est disponible. Les dépendances Compose sont vérifiées au démarrage ; une panne ultérieure ne provoque pas automatiquement le redémarrage des services dépendants. Voir l’ordre de démarrage Compose.

2. depends_on avec condition#

C'est le point que la plupart des fichiers Compose ratent. Un depends_on nu ne fait qu'ordonner le lancement : Docker démarre le conteneur A avant le B, sans jamais vérifier que A fonctionne. Ici, chaque dépendance porte une condition :

api:
  depends_on:
    migrate:
      condition: service_completed_successfully   # le schéma est en place
    pgbouncer:
      condition: service_healthy                  # le pooler répond
    valkey:
      condition: service_healthy
    rabbitmq:
      condition: service_healthy
    mailpit:
      condition: service_started                  # démarré suffit

Le graphe de démarrage#

Le worker est le plus contraint : il attend les migrations, le pooler, le broker, Mailpit… et l'API en bonne santé. Ce dernier lien n'est pas une nécessité technique — le worker ne parle jamais à l'API. C'est un choix de confort en développement : si l'API ne démarre pas, on veut le voir sans que les logs du worker ne défilent par-dessus.

Ce que Compose fait mieux que Kubernetes#

La comparaison n'est pas à sens unique, et il serait malhonnête de présenter le cluster comme un progrès sur toute la ligne.

L'ordre de démarrage est le cas le plus frappant : Kubernetes n'a pas d'équivalent direct de depends_on: condition. Un pod démarre quand le scheduler le décide, et on rétablit la séquence avec des sondes de readiness, des initContainers, un Job barrière et des kubectl wait dans le script de déploiement. Ce que Compose exprime en trois lignes se répartit dans quatre mécanismes.

Ce qu'on emporte vers le cluster#

Écrire le Compose d'abord n'est pas une étape jetable : les décisions qu'on y prend se retrouvent presque toutes, et c'est ce qui rend la traduction si rapide.

La seule décision qui ne se transporte pas est justement l'ordre de démarrage : il faut le réexprimer autrement. Tout le reste est une traduction de vocabulaire.

À retenir#

• Un depends_on nu ne garantit rien : sans condition, il n'ordonne que le lancement.
• Un healthcheck interroge le service dans sa langue — un port ouvert ne veut pas dire prêt.
• service_completed_successfully transforme un conteneur éphémère en barrière : c'est le Job Alembic avant l'heure.
• Compose reste meilleur pour développer : démarrage, rechargement à chaud, ordre déclaratif.
• Presque toutes les décisions se transportent vers le cluster — sauf l'ordre de démarrage, qu'il faut réexprimer en quatre mécanismes.