Docker Compose : décrire et lancer vos conteneurs

Cet article suit la documentation de Docker Compose, relue le 14 octobre 2026. Il suppose Docker installé avec le paquet docker-compose-plugin, qui fournit la commande docker compose (avec une espace). L'ancienne commande docker-compose, avec un tiret, est abandonnée. Pour l'installation, voir Installer Docker sur Ubuntu ou Debian.

Le fichier compose.yaml

Un fichier compose liste des services. Chaque service devient un conteneur. Voici un exemple minimal qui sert une page web avec nginx :

services:
  web:
    image: nginx:stable
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - ./site:/usr/share/nginx/html:ro

Ligne par ligne :

• image donne l'image à télécharger, avec son étiquette. Écrire une étiquette plutôt que latest permet de savoir ce qui tourne.
• restart: unless-stopped relance le conteneur après un redémarrage du serveur, sauf si vous l'avez arrêté vous-même.
• ports publie le port 80 du conteneur sur le port 8080 du serveur, sur 127.0.0.1 seulement : la page n'est joignable que depuis le serveur lui-même, ce qui convient quand un proxy HTTPS la sert à l'extérieur.
• volumes monte le dossier ./site du serveur dans le conteneur, en lecture seule.

Le nom de fichier attendu est compose.yaml. Les anciens fichiers docker-compose.yml sont encore lus, et le champ version qu'on trouve en tête des vieux exemples n'est plus utile.

Les commandes à connaître

Placez-vous dans le dossier qui contient compose.yaml, puis :

1. Vérifier le fichier : docker compose config affiche la configuration complète telle que Compose la comprend, ou l'erreur de syntaxe s'il y en a une.
2. Lancer : docker compose up -d télécharge les images manquantes, crée les conteneurs et les démarre en arrière-plan.
3. Voir ce qui tourne : docker compose ps liste les conteneurs du projet et leur état.
4. Lire les journaux : docker compose logs -f web suit les journaux du service web en direct. Ctrl+C arrête la lecture, pas le conteneur.
5. Arrêter : docker compose down arrête et supprime les conteneurs et le réseau du projet. Vos volumes nommés sont gardés ; docker compose down -v les supprime aussi, avec leurs données.

Mettre une application à jour

Pour passer à une nouvelle version d'une image :

1. Changez l'étiquette dans compose.yaml si vous l'avez figée.
2. Téléchargez les nouvelles images avec docker compose pull.
3. Relancez avec docker compose up -d : Compose ne recrée que les conteneurs dont l'image ou la configuration a changé.
4. Une fois que tout fonctionne, libérez la place des anciennes images avec docker image prune.

Faites une sauvegarde des volumes avant une mise à jour majeure : une application qui migre sa base de données au démarrage ne revient pas toujours en arrière.

Les variables et les secrets

Ne recopiez pas un mot de passe dans compose.yaml si ce fichier va dans un dépôt Git. Compose lit un fichier .env placé à côté de lui, et remplace ${NOM} par sa valeur :

services:
  base:
    image: postgres:17
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - donnees:/var/lib/postgresql/data

volumes:
  donnees:

Le fichier .env contient alors une ligne POSTGRES_PASSWORD= suivie d'une valeur longue et aléatoire. Donnez-lui des droits restreints avec chmod 600 .env, et ajoutez-le au .gitignore. La base n'a pas de section ports : les autres services du même fichier la joignent par son nom, base, sur le réseau que Compose crée pour le projet, et rien n'est ouvert vers l'extérieur.

Exposer une application sur Internet

Ne publiez pas une application directement sur un port ouvert à tous. Un port publié par Docker est joignable de partout par défaut, et il passe à côté du pare-feu ufw, comme le rappelle la page de Docker sur la publication de ports. Publiez sur 127.0.0.1, comme dans le premier exemple, et placez devant un proxy inverse qui sert l'application en HTTPS sur le port 443, avec un certificat. Nginx Proxy Manager, Caddy ou Traefik font ce travail, et des outils comme Coolify ou Dokploy le règlent pour vous.

Sur un VPS Hubspace

Docker et la commande docker compose sont installés à la livraison, et le compte admin peut s'en servir sans sudo. Seuls les ports 22, 80 et 443 sont ouverts depuis Internet, y compris pour les ports publiés par Docker : un proxy sur 80 et 443 suffit à servir toutes vos applications sans rien ouvrir d'autre. Pour un autre port, voir Ouvrir un port sur un serveur. Les ports 25 et 465 sortants sont bloqués : une application qui envoie des courriels doit passer par un service d'envoi.

Des exemples complets, proxy HTTPS compris : n8n, Nextcloud et Vaultwarden.

Questions fréquentes