Docker Compose : décrire ses services dans un fichier

1. Pourquoi Compose

2. La structure du fichier

services:            # les conteneurs de l'application
  nom-du-service:
    image: …         # l'image et sa version
    restart: …       # la politique de redémarrage
    ports: […]       # les ports publiés sur l'hôte
    environment: …   # les variables de configuration
    volumes: […]     # les données persistantes
    depends_on: …    # les services à démarrer avant

volumes:             # les volumes nommés utilisés plus haut
  nom-du-volume:

networks:            # facultatif : réseaux supplémentaires

Le fichier s'appelle compose.yaml (les anciens noms docker-compose.yml restent reconnus). L'indentation se fait avec des espaces, jamais des tabulations, et elle a un sens : deux espaces par niveau.

Rangez chaque application dans son propre dossier, par exemple /opt/forgejo/. Le nom du dossier devient le nom du projet, qui préfixe les conteneurs, volumes et réseaux créés.

3. Un exemple complet : Forgejo et PostgreSQL

Forgejo est une forge Git libre, auto-hébergeable, qui stocke ses données dans une base PostgreSQL. C'est un bon exemple d'application à deux services.

Le fichier des secrets : .env

sudo mkdir -p /opt/forgejo
cd /opt/forgejo

Créez /opt/forgejo/.env :

POSTGRES_PASSWORD=remplacez-par-un-mot-de-passe-long
FORGEJO_VERSION=16

Générez un mot de passe solide avec openssl rand -base64 32, puis protégez le fichier :

sudo chmod 600 /opt/forgejo/.env

Compose lit automatiquement le fichier .env placé à côté de compose.yaml et remplace les ${VARIABLE} du fichier par leur valeur.

Le fichier compose.yaml

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:${FORGEJO_VERSION}
    container_name: forgejo
    restart: unless-stopped
    environment:
      USER_UID: "1000"
      USER_GID: "1000"
      FORGEJO__database__DB_TYPE: postgres
      FORGEJO__database__HOST: db:5432
      FORGEJO__database__NAME: forgejo
      FORGEJO__database__USER: forgejo
      FORGEJO__database__PASSWD: ${POSTGRES_PASSWORD}
    volumes:
      - forgejo-data:/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "192.168.1.10:3000:3000"
      - "192.168.1.10:2222:22"
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17-alpine
    container_name: forgejo-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: forgejo
      POSTGRES_USER: forgejo
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - forgejo-db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U forgejo -d forgejo"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  forgejo-data:
  forgejo-db:

Démarrer et vérifier

Vérifiez d'abord la syntaxe et le remplacement des variables :

sudo docker compose config

La commande affiche le fichier final, variables remplacées, ou une erreur précise. Puis démarrez :

sudo docker compose up -d
sudo docker compose ps

NAME         IMAGE                            SERVICE   STATUS                    PORTS
forgejo      codeberg.org/forgejo/forgejo:16  forgejo   Up 20 seconds             192.168.1.10:3000->3000/tcp, 192.168.1.10:2222->22/tcp
forgejo-db   postgres:17-alpine               db        Up 31 seconds (healthy)

Ouvrez http://192.168.1.10:3000 et terminez l'assistant d'installation de Forgejo : les paramètres de base de données sont déjà remplis. Créez le compte administrateur (par exemple spo).

4. Les commandes du quotidien

Toutes se lancent dans le dossier qui contient compose.yaml (ou avec -f /opt/forgejo/compose.yaml).

5. Mettre à jour

1. Lisez les notes de version de l'application : une version majeure peut demander une migration.
2. Sauvegardez (partie 6).
3. Changez la version dans .env si vous suivez une version précise, puis :

sudo docker compose pull
sudo docker compose up -d
sudo docker image prune

Compose recrée uniquement les conteneurs dont l'image a changé. Suivez les journaux (docker compose logs -f) pendant le redémarrage.

6. Sauvegarder

Une sauvegarde d'application Compose comprend trois éléments :

Export de la base PostgreSQL, sans arrêter le service :

sudo docker compose exec -T db pg_dump -U forgejo -d forgejo | gzip > forgejo-db-$(date +%F).sql.gz

Archive du volume de données, service arrêté pour garantir la cohérence :

sudo docker compose stop forgejo
sudo docker run --rm -v forgejo_forgejo-data:/data:ro -v "$PWD":/sauvegarde debian:13 tar czf /sauvegarde/forgejo-data-$(date +%F).tar.gz -C /data .
sudo docker compose start forgejo

Le nom réel du volume est préfixé par le nom du projet (forgejo_forgejo-data) : vérifiez-le avec docker volume ls. Copiez ensuite ces archives hors du serveur (voir la règle 3-2-1), et testez une restauration.

7. Les bonnes pratiques

À retenir

• compose.yaml décrit toute l'application ; les services se joignent par leur nom dans un réseau privé.
• Secrets dans .env (droits 600, jamais dans Git), versions d'images fixées.
• docker compose up -d, ps, logs -f, pull, down : les cinq commandes du quotidien.
• down -v supprime les données : à manier avec précaution.
• Sauvegarde = configuration + export de la base + volumes, copiée hors du serveur et testée.