Docker Compose : orchestrer une stack locale

Un conteneur isolé, c’est un bon début. Mais une application web, c’est presque toujours une stack : une API, une base de données, parfois un reverse proxy ou un worker. Docker Compose décrit ces services dans un fichier YAML, les démarre ensemble, leur fournit un réseau, des volumes et des variables d’environnement. Le tout avec une commande : docker compose up.

Ce guide montre comment monter une stack locale crédible, sans transformer votre portable en cluster Kubernetes.

Compose en une idée

Compose lit un fichier, le plus souvent compose.yaml, qui déclare :

• des services : les conteneurs à lancer ;
• des réseaux : la façon dont ils communiquent ;
• des volumes : ce qui doit persister ;
• éventuellement des configurations et des secrets, selon l’environnement.

Les commandes de base :

# Démarrer tous les services en arrière-plan
docker compose up -d
# Lister l'état des services
docker compose ps
# Suivre les journaux du service api
docker compose logs -f api
# Arrêter et supprimer les conteneurs du projet
docker compose down

L’option -d détache les conteneurs du terminal. La commande down supprime les conteneurs et le réseau du projet, mais conserve les volumes nommés, sauf si vous ajoutez --volumes. La documentation officielle de Compose et la référence du fichier Compose détaillent chaque option.

Exemple : une API Node, Postgres et Caddy

Voici l’arborescence du projet :

projet/
  compose.yaml
  api/
    Dockerfile
    package.json
    server.js
  Caddyfile

Et un compose.yaml simplifié :

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 5s
      timeout: 5s
      retries: 10

  api:
    build: ./api
    environment:
      DATABASE_URL: postgres://app:app@db:5432/app
      NODE_ENV: development
    volumes:
      # Le code est monté pour le rechargement à chaud
      - ./api:/usr/src/app
      # Volume anonyme : conserve les node_modules du conteneur
      - /usr/src/app/node_modules
    ports:
      - "3000:3000"
    depends_on:
      db:
        condition: service_healthy

  proxy:
    image: caddy:2
    ports:
      - "8080:80"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
    depends_on:
      - api

volumes:
  pgdata:

Le Caddyfile minimal :

:80 {
  reverse_proxy api:3000
}

Quelques points à remarquer :

• le nom d’hôte db désigne le service Postgres sur le réseau Compose ;
• DATABASE_URL utilise db et non localhost : dans un conteneur, localhost désigne le conteneur lui-même ;
• le volume nommé pgdata assure la persistance des données ;
• depends_on associé à un healthcheck fait attendre l’API jusqu’à ce que la base soit réellement prête, et pas seulement démarrée ;
• le montage du code permet le rechargement à chaud, et le volume anonyme sur node_modules évite d’écraser les modules compilés pour Linux par ceux de votre machine.

Ouvrez ensuite http://localhost:8080 : le proxy relaie vers l’API. En équipe, ce socle remplace dix README contradictoires. Si vous souhaitez le déléguer, l’agence Yunt peut livrer ce type de stack avec le dépôt.

Le workflow du quotidien

Démarrer et arrêter

docker compose up -d --build
docker compose stop
docker compose start
docker compose down

L’option --build reconstruit les images si un Dockerfile a changé. Pour comprendre ce que contient ./api/Dockerfile, reportez-vous à l’article Dockerfile expliqué : construire une image web.

Journaux et accès aux conteneurs

docker compose logs -f --tail=100
docker compose exec api sh
docker compose exec db psql -U app -d app

exec ouvre une commande dans un service déjà lancé, tandis que run crée un conteneur ponctuel.

Migrations et jeux de données

docker compose exec api npm run migrate
docker compose exec api npm run seed

Préférez des scripts de données idempotents, que l’on peut rejouer sans casser la base, à un gros export SQL opaque.

Repartir de zéro

docker compose down --volumes

Cette commande efface les volumes nommés du projet. Idéale pour repartir propre, elle est dangereuse si vous y conserviez des données uniques sans sauvegarde.

Réseau et variables d’environnement

Le piège de localhost

Dans Compose, les services se joignent par leur nom de service. Depuis votre machine (navigateur, client SQL), vous passez par les ports publiés. Depuis le conteneur api, localhost:5432 ne pointe pas vers Postgres : utilisez db:5432. Cette confusion est l’erreur la plus fréquente des débutants.

Fichier .env

Compose charge un fichier .env voisin pour l’interpolation de variables :

environment:
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

Trois habitudes à adopter : ignorer .env dans Git, versionner un .env.example, et ne jamais mettre de secret de production « pour tester vite ».

Organiser le dépôt pour l’équipe

Un fichier Compose utile est un contrat :

• un parcours nominal documenté pour le premier jour ;
• un README qui indique les prérequis, le premier démarrage, les données de départ et le dépannage des ports ;
• éventuellement plusieurs fichiers : compose.yaml (socle), compose.override.yaml (développement local, fusionné automatiquement) et un fichier dédié aux tests en CI.

Un premier démarrage peut alors tenir en trois commandes :

cp .env.example .env
docker compose up -d --build
docker compose exec api npm run seed

Worker, outils et profils

Dès qu’il y a des files de tâches (envoi d’e-mails, miniatures), un service worker réutilise l’image de l’API avec une autre commande :

worker:
    build: ./api
    command: ["node", "worker.js"]
    environment:
      DATABASE_URL: postgres://app:app@db:5432/app
    depends_on:
      db:
        condition: service_healthy

Pour des outils occasionnels comme Mailpit (réception d’e-mails de test), les profils permettent de ne les démarrer qu’à la demande :

mail:
    image: axllent/mailpit
    ports:
      - "8025:8025"
      - "1025:1025"
    profiles: ["tools"]

docker compose --profile tools up -d

Erreurs fréquentes

• Oublier de reconstruire après une modification du Dockerfile : utilisez --build ou docker compose build.
• Port déjà utilisé : changez le port côté hôte ou arrêtez l’ancien projet ; l’option -p permet d’isoler les noms de projets.
• Données perdues : sans volume, les données sont éphémères. Vérifiez la section volumes.
• depends_on sans healthcheck : un conteneur « démarré » ne signifie pas que Postgres accepte des connexions.
• Tout exposer sans réfléchir : publier le port de la base est pratique en local, mais sachez qui peut atteindre votre machine.

Quand un bug n’apparaît « que dans Compose », comparez d’abord les variables d’environnement et les noms d’hôtes. Enfin, ne publiez jamais tel quel un fichier Compose de développement (mots de passe triviaux, code monté, mode debug) sur Internet. Pour une base solide côté production, consultez les bonnes pratiques Docker pour projets web.

Quand Compose atteint ses limites

Compose reste excellent en local et pour de petits déploiements. Il montre ses limites quand vous avez besoin de :

• répartir automatiquement la charge sur plusieurs machines ;
• placer finement les charges de travail sur des nœuds ;
• profiter d’un écosystème riche de contrôleurs cloud ;
• appliquer des politiques réseau très fines.

Kubernetes ou une plateforme managée prennent alors le relais. Beaucoup d’équipes web se contentent longtemps de Compose en local et d’un hébergeur qui gère l’exécution. Choisir l’outil au bon moment évite la sur-ingénierie. Pour situer Docker par rapport à la virtualisation, lisez À quoi sert Docker pour un développeur web.

Conclusion

Docker Compose orchestre une stack locale : services, réseau, volumes, variables et journaux. Pour un développeur web, c’est souvent l’outil qui rend Docker réellement utile au quotidien, bien au-delà d’une démonstration avec Nginx.

Écrivez un compose.yaml minimal (API et base), faites parler l’API avec le nom d’hôte du service, ajoutez un healthcheck et documentez les commandes up, down et seed. Enrichissez ensuite avec un proxy, un worker et des outils. Pour ancrer ces réflexes dans une formation web complète, découvrez Academy Yunt.

FAQ

Faut-il écrire docker-compose ou docker compose ?

Préférez docker compose, le plugin intégré à Docker (version 2). L’ancien binaire docker-compose disparaît peu à peu des tutoriels sérieux.

Compose remplace-t-il Kubernetes ?

Non. Compose brille en développement local et pour de petits déploiements. Kubernetes répond à d’autres enjeux d’orchestration à grande échelle.

Peut-on faire du rechargement à chaud ?

Oui, avec un volume qui monte le code et un processus de développement (nodemon, Vite…). Gardez une image de production sans ce montage.

Faut-il publier le port de la base ?

C’est utile pour un client SQL installé sur votre machine. Sinon, le réseau interne de Compose suffit.

Où lancer les migrations de base de données ?

Évitez les migrations destructives automatiques au démarrage. Préférez une commande explicite ou une étape de votre pipeline de déploiement.