Docker : Docker Compose

Docker Compose décrit une application composée de plusieurs services (conteneurs, volumes, réseaux) dans un fichier compose.yaml, et la pilote avec une seule commande. La commande est docker compose (avec un espace) ; l’ancien outil docker-compose n’est plus maintenu.

Exemple de compose.yaml

services:
  web:
    image: nginx:alpine
    ports:
      - '127.0.0.1:8080:80'
    volumes:
      - ./site:/usr/share/nginx/html:ro
    depends_on:
      api:
        condition: service_healthy
    restart: unless-stopped

  api:
    build: ./api
    environment:
      DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app
    healthcheck:
      test: ['CMD', 'wget', '-qO-', 'http://localhost:3000/sante']
      interval: 30s
    depends_on:
      - db

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Tous les services d’un même fichier partagent un réseau créé automatiquement : ils se joignent par leur nom de service (db, api). Le champ version: n’est plus nécessaire.

Variables d’environnement

Compose lit automatiquement un fichier .env placé à côté de compose.yaml pour remplacer les ${VARIABLE} :

DB_PASSWORD=<mot-de-passe-long-et-aleatoire>

Attention

Le fichier .env contient des secrets : l’exclure de Git (.gitignore) et ne jamais le publier.

Commandes essentielles

Commande	Rôle
docker compose up -d	Crée et démarre les services en arrière-plan
docker compose up -d --build	Reconstruit les images avant de démarrer
docker compose down	Arrête et supprime conteneurs et réseaux
docker compose down -v	Idem, et supprime les volumes
docker compose ps	État des services
docker compose logs -f api	Suit les logs d’un service
docker compose exec api sh	Shell dans un service en marche
docker compose run --rm api sh	Lance un conteneur ponctuel basé sur un service
docker compose build	Construit les images locales
docker compose pull	Télécharge les images à jour
docker compose restart api	Redémarre un service
docker compose stop / start	Arrête / relance sans supprimer
docker compose config	Valide le fichier et affiche la configuration finale
docker compose ls	Liste les projets Compose

Ajouter le nom d’un service pour limiter une commande à celui-ci (docker compose up -d api).

Mettre à jour une application

docker compose pull          # nouvelles images
docker compose up -d         # recrée uniquement les services dont l'image a changé
docker image prune           # supprime les anciennes images

Plusieurs fichiers et profils

docker compose -f compose.yaml -f compose.prod.yaml up -d   # fusionne plusieurs fichiers

Un fichier compose.override.yaml, s’il existe, est fusionné automatiquement : pratique pour des réglages de développement.

Les profils activent des services optionnels :

services:
  adminer:
    image: adminer
    profiles: ['debug']

docker compose --profile debug up -d

Nom du projet

Les conteneurs, réseaux et volumes sont préfixés par le nom du dossier. Le modifier avec -p ou la clé name: :

docker compose -p monprojet up -d

Dépannage

Symptôme	Piste
variable is not set	Variable absente de .env ou de l’environnement
Un service redémarre en boucle	docker compose logs -f service
Les modifications du code ne sont pas prises en compte	docker compose up -d --build
Une base de données est vide après down	down -v supprime les volumes : utiliser down seul
Un service ne joint pas un autre	Utiliser le nom du service comme hôte, pas localhost

Pour aller plus loin

• Documentation officielle : docs.docker.com/compose
• Référence du fichier : docs.docker.com/reference/compose-file

Dans la même rubrique

• Commandes générales
• Images
• Conteneurs
• Volumes
• Réseau
• Docker Compose