Écran d’un portable affichant le fichier compose.yaml et la commande docker compose up -d.

Docker Compose sous Linux : écrire, lancer, mettre à jour et sauvegarder vos services auto-hébergés

User avatar placeholder
Écrit par Vincent

Mis à jour le 16 octobre 2026

Docker Compose décrit un ou plusieurs conteneurs dans un seul fichier texte, compose.yaml, puis les lance d’une commande : docker compose up -d. Pour mettre un service à jour, docker compose pull télécharge la nouvelle image et docker compose up -d recrée seulement les conteneurs qui ont changé. Vos données survivent à ces opérations tant qu’elles sont rangées dans un volume ou un dossier que vous sauvegardez.

L’essentiel
Les quatre commandes : docker compose up -d (lancer), docker compose ps (contrôler), docker compose logs -f (lire les journaux), docker compose pull puis up -d (mettre à jour).
Prérequis : Docker Engine et le plugin Compose (paquet docker-compose-plugin du dépôt Docker), un dossier par service.
Le piège à connaître : un port publié par Docker passe à travers UFW.
Versions : Docker Compose 5.6.0 (2 octobre 2026), Docker Engine 29.9.1 (14 octobre 2026).
Vérifié les 14 et 16 octobre 2026 sur Debian 13 et sur un banc Ubuntu 24.04 (détail en fin d’article).

Table des matières

Docker Compose, c’est quoi et comment ça fonctionne ?

Docker lance des conteneurs : des applications isolées qui partagent le noyau de votre système. Lancées une par une avec docker run, elles demandent de longues commandes à retaper à chaque mise à jour. Docker Compose range ces réglages dans un fichier, compose.yaml, que vous gardez, sauvegardez et relancez à l’identique.

Un fichier, une pile de services

Un fichier compose.yaml décrit un projet (aussi appelé pile). Chaque entrée de la section services devient un conteneur. Compose crée en plus un réseau propre au projet, sur lequel les services se joignent par leur nom, et les volumes qui gardent les données. Le projet prend le nom de son dossier : un fichier rangé dans ~/site-web donne le projet site-web et le conteneur site-web-web-1. Deux dossiers de même nom, même rangés à des endroits différents, partagent donc le même projet : un down lancé dans l’un supprime les conteneurs de l’autre. Donnez à chaque service un nom de dossier unique.

Fonctionnement de Docker Compose : le fichier compose.yaml crée un projet avec ses conteneurs, son réseau et ses volumes, puis publie des ports sur la machine hôte
Fonctionnement de Docker Compose : le fichier compose.yaml crée un projet avec ses conteneurs, son réseau et ses volumes, puis publie des ports sur la machine hôte

C’est ce qui fait de Compose l’outil de base de l’auto-hébergement : chaque service tient dans un dossier, se met à jour sans toucher aux autres et se reconstruit à partir de son fichier et de ses données. Notre guide pour monter un homelab sous Linux part de ce principe.

Docker Compose ou docker run ?

Les deux lancent le même conteneur. Voici le service de cet article écrit des deux façons :

Avec docker run Avec Docker Compose
docker run -d --name site-web -p 8080:80 -v ~/site-web/site:/usr/share/nginx/html:ro --restart unless-stopped nginx:1.30-alpine Les mêmes réglages dans compose.yaml, puis docker compose up -d
Réglages perdus si vous ne notez pas la commande Réglages écrits dans un fichier versionnable
Mise à jour : arrêter, supprimer, retaper la commande Mise à jour : docker compose pull puis docker compose up -d
Un conteneur à la fois Plusieurs services, leur réseau et leurs volumes ensemble

docker run reste pratique pour un test jetable. Pour un service qui doit tourner des mois, Compose s’impose. Ne confondez pas non plus Compose et Dockerfile : un Dockerfile construit une image, Compose exécute des conteneurs à partir d’images, qu’elles viennent d’un registre comme Docker Hub ou d’un Dockerfile.

docker-compose ou docker compose : quelle version en 2026 ?

La commande à utiliser est docker compose, avec une espace. L’ancienne commande avec un tiret, docker-compose, désignait Compose v1, écrit en Python et abandonné depuis.

Version Commande Langage Statut en octobre 2026
Compose v1 (2014) docker-compose Python Ancienne version, à remplacer
Compose v2 (2020) docker compose Go Encore citée comme prise en charge par Docker, mais plus publiée depuis la 2.40.3 (octobre 2025) ; reste dans les dépôts de certaines distributions
Compose v5 (2025) docker compose Go Version actuelle : 5.6.0 depuis le 2 octobre 2026

Selon la documentation de Docker, la v5 est « fonctionnellement identique » à la v2 : le saut de numéro sert à éviter la confusion avec les anciens formats de fichier « 2.x » et « 3.x ». Les deux ignorent la ligne version: que l’on trouve encore en tête de nombreux fichiers. Compose affiche alors cet avertissement, sans conséquence :

WARN[0000] /home/vous/site-web/compose.yaml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion

Supprimez simplement la ligne. Un fichier actuel commence directement par services:.

Pour savoir quelle version vous utilisez :

docker compose version
Docker Compose version v5.6.0

Docker Compose n’est donc pas dépassé : il est maintenu, publié presque chaque mois et reste la façon standard de décrire des services sur une seule machine. Kubernetes répond à un autre besoin, celui de répartir des services sur plusieurs serveurs.

Installer le plugin Compose selon votre distribution

Compose s’installe avec Docker Engine. Toutes les étapes, du dépôt officiel au premier conteneur, sont dans notre guide pour installer Docker sur Linux. Le point qui piège concerne le nom du paquet : celui de votre distribution n’est pas toujours la dernière version.

Distribution Paquet recommandé Paquet de la distribution
Debian 13 docker-compose-plugin (dépôt Docker), 5.6.0 docker-compose 2.26.1
Ubuntu 24.04 et 26.04 docker-compose-plugin (dépôt Docker), 5.6.0 docker-compose-v2 (2.40.3). Sur Ubuntu 24.04, le paquet docker-compose installe l’ancienne v1 1.29.2 : à éviter
Fedora 43 et 44 docker-compose-plugin (dépôt Docker) docker-compose 5.6.0
Arch Linux docker-compose (dépôts officiels), 5.6.0 identique
openSUSE Tumbleweed docker-compose (dépôts officiels), 5.6.0 identique
openSUSE Leap 16.0 Aucun paquet officiel Paquets expérimentaux seulement (projet Virtualization:containers)

Si Docker vient du dépôt officiel de Docker, le plugin y est déjà, et il se met à jour avec le reste du système. Vérifiez ensuite l’installation avec docker compose version.

Votre premier compose.yaml, pas à pas

L’exemple de cet article sert une page web avec Nginx, à partir de l’image officielle. Il est volontairement simple, mais il utilise tout ce qu’on retrouve dans un vrai service : une image à la version figée, un port, un dossier de données, une politique de redémarrage et un fichier .env.

Un dossier par service

Rangez chaque service dans son propre dossier, avec son fichier compose.yaml, son .env et ses données. Sauvegarder, déplacer ou supprimer un service revient alors à traiter un dossier. La plupart des tutoriels de MémoLinux rangent ces dossiers dans votre dossier personnel (~/vaultwarden, ~/pihole…) ; l’exemple suit la même convention :

mkdir -p ~/site-web/site
cd ~/site-web
echo '<h1>Bonjour depuis Docker Compose</h1>' > site/index.html

Vous obtiendrez cette arborescence :

~/site-web/
├── compose.yaml
├── .env
└── site/
    └── index.html

Écrire le fichier

Créez compose.yaml dans ~/site-web avec l’éditeur de votre choix (nano compose.yaml), et collez :

services:
  web:                                   # nom du service, choisi librement
    image: nginx:${NGINX_TAG}            # image officielle, version lue dans .env
    ports:
      - "${WEB_PORT}:80"                 # port de la machine : port du conteneur
    volumes:
      - ./site:/usr/share/nginx/html:ro  # vos pages, montées en lecture seule
    restart: unless-stopped              # relancé au démarrage de la machine

Puis créez le fichier .env dans le même dossier :

# ~/site-web/.env : valeurs lues par compose.yaml
NGINX_TAG=1.30-alpine
WEB_PORT=8080

Le YAML est sensible à l’indentation : deux espaces par niveau, jamais de tabulation. Le chemin /usr/share/nginx/html et le port 80 viennent des exemples de la page officielle de l’image Nginx sur Docker Hub ; pour une autre application, ces valeurs se lisent dans sa documentation.

Vérifier avant de lancer : docker compose config

Cette commande lit le fichier, remplace les variables du .env et affiche la configuration que Docker appliquera. Une faute d’indentation y provoque une erreur, avant tout lancement.

docker compose config
name: site-web
services:
  web:
    restart: unless-stopped
    image: nginx:1.30-alpine
    networks:
      default: null
    volumes:
      - type: bind
        source: /home/vous/site-web/site
        target: /usr/share/nginx/html
        read_only: true
        bind: {}
    ports:
      - mode: ingress
        target: 80
        published: "8080"
        protocol: tcp
networks:
  default:
    name: site-web_default

La ligne image: nginx:1.30-alpine prouve que le .env a bien été lu. Pour un simple contrôle sans affichage, docker compose config -q ne dit rien si tout va bien et affiche l’erreur sinon.

Une variable absente du .env, en revanche, n’est pas une erreur : Compose affiche seulement The "WEB_PORT" variable is not set. Defaulting to a blank string. et continue. Sans WEB_PORT, le service démarre alors sur un port choisi au hasard, ouvert sur toutes les interfaces. Pour qu’une variable indispensable bloque le lancement, écrivez-la ainsi dans compose.yaml :

      - "${WEB_PORT:?WEB_PORT manquant dans .env}:80"

Compose s’arrête alors avec required variable WEB_PORT is missing a value: WEB_PORT manquant dans .env.

Lancer et contrôler

docker compose up -d
docker compose ps
NAME             IMAGE               COMMAND                  SERVICE   CREATED        STATUS                  PORTS
site-web-web-1   nginx:1.30-alpine   "/docker-entrypoint.…"   web       1 second ago   Up Less than a second   0.0.0.0:8080->80/tcp, [::]:8080->80/tcp

L’option -d (pour detached) rend la main tout de suite : sans elle, Compose affiche les journaux en continu, et Ctrl+C arrête les conteneurs. Ouvrez ensuite http://adresse-de-la-machine:8080 dans un navigateur : la page « Bonjour depuis Docker Compose » s’affiche. Sur la machine elle-même, curl http://localhost:8080 donne le même résultat.

En cas de doute, les journaux disent ce qui se passe :

docker compose logs -f

Ctrl+C quitte l’affichage sans arrêter le service.

Les commandes Docker Compose à connaître

Toutes se lancent depuis le dossier qui contient compose.yaml. Ajoutez un nom de service à la fin pour n’agir que sur lui (docker compose restart web).

Commande Effet
docker compose up -d Crée et démarre les services ; recrée ceux dont la configuration ou l’image a changé
docker compose up -d web Ne démarre que le service web (et ses dépendances)
docker compose ps Liste les conteneurs du projet et leur état
docker compose logs -f --tail 50 Suit les journaux, en partant des 50 dernières lignes
docker compose stop / start Arrête ou redémarre les conteneurs, sans les supprimer
docker compose restart Redémarre les conteneurs, sans relire compose.yaml
docker compose down Arrête et supprime les conteneurs et le réseau du projet ; garde les volumes
docker compose pull Télécharge les images du fichier, sans redémarrer quoi que ce soit
docker compose exec web sh Ouvre un shell dans le conteneur web qui tourne
docker compose run --rm web nginx -v Lance une commande ponctuelle dans un nouveau conteneur du service, supprimé ensuite (--rm)
docker compose config Affiche la configuration finale, variables remplacées
docker compose ls -a Liste tous les projets Compose de la machine, où qu’ils soient ; sans -a, seulement ceux qui tournent

Trois confusions reviennent souvent. up crée les conteneurs quand il le faut, start relance seulement des conteneurs existants. down supprime les conteneurs, stop les garde. Et restart ne prend pas en compte une modification de compose.yaml ou du .env : après une modification, relancez docker compose up -d.

Attention. docker compose down -v (ou --volumes) supprime aussi les volumes nommés déclarés dans le fichier, donc les données qu’ils contiennent. Sans -v, down ne touche ni aux volumes nommés, ni aux dossiers de l’hôte montés dans les conteneurs.

Variables et mots de passe : le fichier .env

Le fichier .env placé à côté de compose.yaml sert à remplacer les ${VARIABLE} du fichier avant le lancement. Il évite d’écrire un mot de passe ou un numéro de version en dur dans compose.yaml, que vous pourrez alors partager ou versionner sans risque.

Deux autres mécanismes existent, à ne pas confondre :

Mécanisme Ce qu’il fait
Fichier .env du projet Remplace les ${...} dans compose.yaml
env_file: dans un service Transmet les variables d’un fichier à l’intérieur du conteneur
environment: dans un service Définit des variables du conteneur dans compose.yaml ; prioritaire sur env_file:

Les vraies applications combinent souvent les deux premiers : notre guide pour installer Immich avec Docker Compose en donne un exemple complet, avec le mot de passe de la base de données dans .env.

Attention aux mots de passe qui contiennent un $ : Compose remplace aussi les variables à l’intérieur du .env. Écrit sans guillemets ou entre guillemets doubles, MDP=abc$def devient abc (avec l’avertissement The "def" variable is not set), et l’application reçoit un autre mot de passe que le vôtre. Entourez-le de guillemets simples, qui le transmettent tel quel :

MDP='abc$def'

Pour voir les valeurs que Compose a réellement lues :

docker compose config --environment

La commande liste aussi les variables de votre session, car elles sont prioritaires sur le .env : une variable WEB_PORT définie dans votre shell l’emporte sur celle du fichier. Pour la même raison, ne collez pas sa sortie sur un forum : elle peut contenir des jetons ou des mots de passe de votre session.

Un .env qui contient des mots de passe ne doit être lisible que par vous :

chmod 600 ~/site-web/.env

Ne le publiez pas sur un dépôt Git, et ne le chargez jamais dans votre shell avec source .env : une valeur contenant un accent grave ou $(…) y serait exécutée comme une commande, et un simple $ y serait remplacé par une variable. Pour relire une valeur, grep NGINX_TAG .env suffit.

Où sont vos données : volume nommé ou dossier de l’hôte ?

Un conteneur est jetable : tout ce qu’il écrit hors d’un volume disparaît quand Compose le recrée, à chaque mise à jour. Les données à garder doivent donc aller dans l’un de ces deux emplacements.

Dossier de l’hôte (bind mount) Volume nommé
Syntaxe dans volumes: ./site:/usr/share/nginx/html donnees:/usr/share/nginx/html, plus une section volumes: en bas du fichier
Emplacement sur le disque Le dossier que vous indiquez, à côté de compose.yaml /var/lib/docker/volumes/<projet>_<volume>/_data, géré par Docker
Contenu au premier lancement Celui de votre dossier ; un dossier vide masque les fichiers de l’image Docker y copie les fichiers que l’image contient à cet endroit
Sauvegarde Copier le dossier du service Passer par un conteneur temporaire, ou lire le dossier de Docker avec sudo
Supprimé par down -v Non Oui
Volume nommé ou dossier de l'hôte avec Docker Compose : emplacement, premier lancement, sauvegarde et suppression comparés
Volume nommé ou dossier de l'hôte avec Docker Compose : emplacement, premier lancement, sauvegarde et suppression comparés

La troisième ligne explique un piège fréquent. Avec un volume nommé, Docker recopie au premier lancement le contenu que l’image place dans ce dossier : la page d’accueil de Nginx apparaît. Avec un dossier de l’hôte vide, rien n’est copié, et le dossier vide masque le contenu de l’image. Si le dossier n’existe pas encore, Docker le crée, mais il appartient alors à root.

Pour l’auto-hébergement, le dossier de l’hôte a un avantage décisif : tout le service tient dans un seul dossier, qu’une copie suffit à sauvegarder. Le volume nommé convient aux applications qui le demandent dans leur documentation, comme Portainer ou Ollama : notre guide pour installer Ollama avec Docker Compose y range les modèles téléchargés, qui pèsent de quelques centaines de mégaoctets à plusieurs gigaoctets.

Un troisième cas piège les bases de données : le volume anonyme. Quand une image déclare un dossier de données (c’est le cas de nombreuses images PostgreSQL ou MariaDB) et que compose.yaml ne le monte nulle part, Docker crée un volume sans nom. Il survit à pull puis up -d, mais après down puis up -d, le conteneur repart sur un volume neuf et vide : les données semblent perdues, et la sauvegarde du dossier ne les contient pas. Vérifiez donc que chaque dossier de données de l’application, tel que le donne sa documentation, apparaît dans la section volumes: du service.

Si une application signale qu’elle ne peut pas écrire dans son dossier, comparez le propriétaire du dossier (ls -ln) avec l’utilisateur du conteneur, que l’option user: permet de fixer. Beaucoup d’images documentent pour cela des variables comme PUID et PGID : leur nom varie d’une image à l’autre, lisez sa documentation.

Ports, réseau et pare-feu : le piège UFW

Publier un port

La ligne "8080:80" signifie : le port 8080 de la machine renvoie vers le port 80 du conteneur. Écrivez-la entre guillemets, comme le recommande la référence Compose, pour éviter qu’un analyseur YAML ne la lise comme un nombre. Sans adresse devant, Docker écoute sur toutes les interfaces de la machine.

Deux services ne peuvent pas publier le même port de la machine. Le second échoue avec ce message :

Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint autre-web2-1 (…): Bind for 0.0.0.0:8080 failed: port is already allocated

Si c’est un programme installé sur la machine, hors Docker, qui occupe le port, le message se termine autrement :

failed to bind host port 0.0.0.0:8080/tcp: address already in use

Dans les deux cas, changez le premier nombre ("8081:80"), ou repérez le programme qui occupe le port avec sudo ss -tlnp | grep 8080.

Les services d’une même pile se parlent par leur nom

Compose crée un réseau pour chaque projet. Un service y joint les autres par leur nom : une application dont le service de base de données s’appelle db s’y connecte à l’adresse db, sur le port interne de la base. Ne publiez donc pas le port d’une base de données : seuls les services qu’un navigateur doit atteindre ont besoin d’une ligne ports:. La directive expose:, que l’on croise dans certains fichiers, n’ouvre rien sur la machine : elle indique seulement un port destiné aux autres conteneurs.

Les ports publiés passent à travers UFW

La documentation de Docker le dit explicitement : avec UFW, le trafic vers un port publié est détourné avant d’atteindre les règles du pare-feu, qui sont alors ignorées. Nous l’avons vérifié : avec UFW actif et la règle « tout refuser en entrée », un serveur web classique devient injoignable depuis une autre machine, mais le conteneur de cet article reste accessible sur le port 8080.

Attention. Sur une machine directement reliée à Internet (serveur loué, VPS, port ouvert sur votre box), un ports: - "8080:80" expose le service au monde entier, quoi que dise ufw status. Ne comptez pas sur UFW pour protéger un port publié par Docker.

Pour un service qui ne doit pas être joignable de l’extérieur, liez le port à l’adresse locale de la machine :

    ports:
      - "127.0.0.1:${WEB_PORT}:80"       # joignable depuis la machine seulement

Sur notre banc, cette ligne a suffi à rendre le service injoignable depuis l’autre machine.

Pour publier ensuite le service en HTTPS, placez devant un reverse proxy, seul à publier les ports 80 et 443 : notre guide Nginx Proxy Manager le met en place. Mais attention : un reverse proxy qui tourne lui-même dans Docker, comme Nginx Proxy Manager, ne peut pas joindre un port lié à 127.0.0.1 : cette adresse désigne alors son propre conteneur, et l’adresse de la machine ne répond pas sur ce port. Dans ce cas, ne publiez aucun port pour le service et branchez-le sur un réseau commun avec le proxy :

services:
  web:
    image: nginx:${NGINX_TAG}
    networks:
      - proxy          # réseau partagé avec le reverse proxy
    restart: unless-stopped

networks:
  proxy:
    external: true     # créé une fois avec : docker network create proxy

Créez ce réseau une seule fois avec docker network create proxy, ajoutez le même bloc networks: au fichier du proxy, puis indiquez au proxy le nom du conteneur comme destination (site-web-web-1, port 80). Sur un serveur à la maison, derrière la box et sans redirection de port, publier un service sur le réseau local reste acceptable, en sachant que ce sont vos règles de box, pas UFW, qui le protègent d’Internet. Notre guide pour configurer UFW reste utile pour tous les services installés hors de Docker, à commencer par SSH.

Docker Compose et depends_on : démarrer la base avant l’application

Une application lancée avant sa base de données échoue à sa première connexion. La directive depends_on règle l’ordre : Compose démarre d’abord les services dont dépend l’application. Sous sa forme courte, celle de notre tutoriel Nextcloud, elle attend seulement que le conteneur de la base soit lancé, pas que la base réponde :

    depends_on:
      - db

Sur notre banc, avec une base qui mettait 8 secondes à être prête, l’application a démarré moins d’une seconde après elle. Pour attendre une base réellement prête, donnez-lui un test de santé (healthcheck) et posez la condition service_healthy. Voici l’extrait d’une pile avec PostgreSQL, repris de l’exemple de la documentation de Docker :

services:
  app:
    # image, ports et volumes de votre application
    depends_on:
      db:
        condition: service_healthy   # attend que la base réponde
    restart: unless-stopped
  db:
    image: postgres:18
    # environment : POSTGRES_USER, POSTGRES_PASSWORD et POSTGRES_DB
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 10s
      retries: 5
      start_period: 30s
    restart: unless-stopped

Le double $$ empêche Compose de remplacer la variable par une valeur du .env : le test reçoit ${POSTGRES_USER} tel quel, et c’est le conteneur qui le lit. Avec cette condition, docker compose up -d attend que la base passe à l’état healthy avant de lancer l’application, et docker compose ps affiche (healthy) dans la colonne STATUS.

Si le test échoue jusqu’au bout, Compose s’arrête sur ce message, et l’application reste créée sans être démarrée :

dependency failed to start: container mon-service-db-1 is unhealthy

Une limite à connaître : depends_on n’agit que lorsque vous lancez Compose. Au redémarrage de la machine ou de Docker, c’est Docker qui relance les conteneurs, sans attendre la base. Sur notre banc, après un redémarrage de Docker, l’application est repartie en même temps que la base, a échoué, puis a été relancée sept fois par Docker avant de se connecter. C’est restart: unless-stopped qui l’a relancée : gardez cette politique sur l’application comme sur la base.

Redémarrage automatique : restart: unless-stopped

La politique de redémarrage décide de ce que fait Docker quand le conteneur s’arrête ou que la machine redémarre.

Valeur Après un plantage Après un redémarrage de Docker ou de la machine
no (par défaut) Pas de redémarrage Pas de redémarrage
on-failure Redémarre si le code de sortie signale une erreur Pas de redémarrage
always Redémarre Redémarre, même si vous l’aviez arrêté à la main
unless-stopped Redémarre Redémarre, sauf si vous l’aviez arrêté à la main

unless-stopped est le bon choix pour un service auto-hébergé : il revient après une coupure de courant, mais un service que vous avez arrêté exprès avec docker compose stop le reste. Pour que vos services démarrent avec la machine, Docker doit lui-même démarrer au boot. C’est le cas par défaut sur Debian et Ubuntu, selon la documentation de Docker ; sur les autres distributions, activez-le :

sudo systemctl enable docker.service containerd.service

Mettre à jour un service sans rien casser

Une mise à jour se fait en deux commandes, mais une mise à jour sûre commence avant et se termine après.

Les six étapes d'une mise à jour Docker Compose sûre : sauvegarder, lire les notes de version, télécharger l'image, recréer le conteneur, vérifier les journaux, nettoyer les anciennes images
Les six étapes d'une mise à jour Docker Compose sûre : sauvegarder, lire les notes de version, télécharger l'image, recréer le conteneur, vérifier les journaux, nettoyer les anciennes images

Tag figé ou latest ?

Le tag est la partie après les deux-points dans nginx:1.30-alpine. Il décide de ce que pull téléchargera :

Tag Exemple Ce que fait pull
Version exacte nginx:1.30.5-alpine Au plus une reconstruction de la même version, puis plus rien une fois cette version dépassée, y compris les correctifs de sécurité
Branche nginx:1.30-alpine Les nouvelles versions de la branche 1.30 (1.30.5, 1.30.6…), sans passer à 1.31
latest nginx:latest La dernière version publiée, y compris une version majeure qui change la configuration

Le tag de branche est le bon compromis pour la plupart des services. Évitez latest pour toute application qui migre sa base de données entre deux versions majeures (Nextcloud, Immich, PostgreSQL) : une mise à jour non prévue peut l’empêcher de redémarrer. Les tags disponibles se lisent sur la page de l’image, sur Docker Hub ou sur le dépôt du projet.

Les commandes de la mise à jour

Avant de commencer, faites une sauvegarde (section suivante) et lisez les notes de version de l’application si elle a changé de version majeure. Puis, dans le dossier du service :

cd ~/site-web
docker compose pull      # télécharge les nouvelles images
docker compose up -d     # recrée les conteneurs dont l'image a changé
docker compose ps        # vérifie que le service tourne
docker compose logs --tail 30

Inutile de lancer docker compose down avant : up -d ne recrée que les conteneurs dont l’image ou la configuration a changé, et laisse les autres tourner. À l’inverse, up -d seul ne suffit pas : sans pull, Compose réutilise l’image déjà présente sur la machine, même si une version plus récente existe sous le même tag.

Une fois le service vérifié, supprimez les anciennes images, qui occupent de la place à chaque mise à jour :

docker image prune

La commande demande confirmation et ne supprime que les images devenues orphelines. Avec -a, docker image prune supprime en plus toutes les images qu’aucun conteneur n’utilise, y compris celles d’un service passé par down, qui seront retéléchargées au prochain lancement, éventuellement dans une version plus récente que prévu. docker system prune va plus loin : il supprime d’abord tous les conteneurs arrêtés, y compris ceux d’un service que vous avez arrêté exprès. Et méfiez-vous de docker volume prune -a, souvent conseillé sur les forums : il efface tous les volumes nommés qu’aucun conteneur n’utilise, donc ceux de chaque service passé par down, avec leurs données.

Revenir en arrière

Avec un tag de branche comme 1.30-alpine, il n’existe pas d’« ancien tag » à remettre : pull a déplacé le même tag vers la nouvelle version. Notez donc, avant le pull, l’empreinte de l’image en service :

docker image inspect --format '{{index .RepoDigests 0}}' nginx:1.30-alpine
nginx@sha256:3af1bab113c2399ca161c98abcfb33e5d7decb4d4c3c8bb8ccd05a73808708f2

L’empreinte affichée chez vous sera différente : c’est elle qu’il faut noter.

Si la nouvelle version pose problème, remettez cette version dans le .env, soit par son numéro exact s’il est publié (NGINX_TAG=1.30.4-alpine), soit par son empreinte (NGINX_TAG=1.30-alpine@sha256:3af1… avec l’empreinte complète), puis relancez :

docker compose up -d

Compose recrée le conteneur avec l’ancienne image, retéléchargée si docker image prune l’a supprimée : attendez donc d’avoir vérifié la nouvelle version avant de nettoyer. Cette marche arrière suffit pour une application sans base de données. Si la nouvelle version a déjà migré ses données, l’ancienne ne saura pas les relire : il faut alors restaurer la sauvegarde faite juste avant la mise à jour.

Mettre à jour plusieurs services d’un coup

Si chacun de vos services a son dossier dans votre dossier personnel, cette boucle les met à jour l’un après l’autre :

for f in ~/*/compose.yaml ~/*/docker-compose.yml; do
  [ -e "$f" ] || continue   # motif sans correspondance : on passe
  echo "== Mise à jour de ${f%/*}"
  docker compose -f "$f" pull && docker compose -f "$f" up -d
done

Compose lit le .env du dossier de chaque fichier, même lancé depuis ailleurs. Si pull échoue, && empêche up -d de s’exécuter pour ce service, et la boucle passe au suivant.

La boucle couvre les deux noms de fichier utilisés dans nos tutoriels, compose.yaml et docker-compose.yml, et traite tous les dossiers de premier niveau qui en contiennent un : une copie de sauvegarde d’un service rangée dans votre dossier personnel serait relancée comme un service à part entière. Réservez cette boucle aux services dont les tags sont figés sur une branche, et sortez-en ceux qui demandent une procédure de mise à jour, comme Nextcloud ou Immich lors d’un changement de version majeure.

Et les mises à jour automatiques ?

Watchtower, l’outil le plus cité pour mettre à jour les conteneurs automatiquement, n’est plus maintenu : son dépôt l’annonce en tête de page. Pour être prévenu sans laisser un outil décider à votre place, un outil de notification comme Diun signale les nouvelles images disponibles, et vous lancez la mise à jour quand vous avez le temps de vérifier.

Mettre à jour Compose lui-même

Le plugin se met à jour avec le système quand il vient du dépôt Docker :

sudo apt update
sudo apt install docker-compose-plugin

Sur Fedora, sudo dnf upgrade suffit. Lisez les notes de version avant un saut important : la version 5.5.0 prévenait par exemple que les conteneurs existants pouvaient être recréés au premier docker compose up après la mise à jour, ce qui provoque une courte coupure de chaque service.

Sauvegarder et restaurer une pile Compose

Un service Compose se reconstruit à partir de trois éléments : compose.yaml, .env et les données. Avec la convention « un dossier par service », sauvegarder revient à archiver ce dossier, service arrêté pour que les fichiers ne changent pas pendant la copie :

mkdir -p ~/sauvegardes
cd ~/site-web
docker compose stop
sudo tar -czf ~/sauvegardes/site-web-$(date +%F).tar.gz -C ~ site-web
sudo chown "$USER": ~/sauvegardes/site-web-$(date +%F).tar.gz   # l'archive revient à votre compte
chmod 600 ~/sauvegardes/site-web-$(date +%F).tar.gz             # lisible par vous seul : elle contient le .env
docker compose start

sudo est nécessaire parce que les conteneurs créent souvent des fichiers appartenant à root ou à un autre utilisateur. L’archive créée par sudo appartient elle aussi à root : sans le chown, une copie automatique lancée avec votre compte s’arrêterait sur Permission denied. Pour une application avec base de données, ajoutez avant l’arrêt l’export de la base que décrit sa documentation : nos tutoriels Vaultwarden et Nextcloud détaillent chacun le leur.

Une sauvegarde n’existe vraiment qu’une fois restaurée. Pour la tester, mettez l’ancien dossier de côté plutôt que de le supprimer, puis restaurez :

docker compose -f ~/site-web/compose.yaml down
mv ~/site-web ~/sauvegardes/site-web.avant-restauration
sudo tar -xzf ~/sauvegardes/site-web-AAAA-MM-JJ.tar.gz -C ~
cd ~/site-web
docker compose up -d

Remplacez AAAA-MM-JJ par la date de l’archive. L’ancien dossier part dans ~/sauvegardes et non à côté du service : une copie laissée dans votre dossier personnel serait prise pour un service de plus par la boucle de mise à jour vue plus haut. Une fois le service vérifié, supprimez ~/sauvegardes/site-web.avant-restauration, avec sudo si des conteneurs y ont créé des dossiers appartenant à root : sans lui, la suppression s’arrête sur Permission denied.

Pour un volume nommé, la documentation de Docker passe par un conteneur temporaire qui archive le volume. Arrêtez le service comme plus haut, puis vérifiez d’abord le nom exact du volume : avec une faute de frappe, Docker crée un volume vide et la commande produit une archive vide, sans aucune erreur.

docker volume inspect site-web_donnees --format '{{.Mountpoint}}'
docker run --rm -v site-web_donnees:/donnees:ro -v ~/sauvegardes:/sauvegarde alpine tar -czf /sauvegarde/site-web-donnees.tar.gz -C /donnees .
tar -tzf ~/sauvegardes/site-web-donnees.tar.gz | head

Remplacez site-web_donnees par le nom donné par docker volume ls. Si la première commande répond no such volume, corrigez le nom avant d’aller plus loin ; la dernière doit lister vos fichiers. Pour restaurer l’archive dans le volume, service arrêté :

docker run --rm -v site-web_donnees:/donnees -v ~/sauvegardes:/sauvegarde:ro alpine tar -xzf /sauvegarde/site-web-donnees.tar.gz -C /donnees

Pour copier ces archives automatiquement vers un autre disque, notre guide rsync et crontab prend le relais.

Erreurs courantes

« no configuration file provided: not found »

no configuration file provided: not found

Compose ne trouve pas de fichier compose.yaml (ni docker-compose.yml) dans le dossier courant. Placez-vous dans le dossier du service avec cd, ou indiquez le fichier avec docker compose -f ~/site-web/compose.yaml up -d.

« port is already allocated » ou « address already in use »

Un autre conteneur (premier message), ou un programme de la machine (second message), utilise déjà le port de gauche de la ligne ports:. Changez ce port ou arrêtez l’autre service (voir la section sur les ports).

« the attribute version is obsolete »

Simple avertissement : supprimez la ligne version: en tête du fichier.

« docker-compose: command not found »

Vous suivez un tutoriel écrit pour l’ancienne v1. Remplacez docker-compose par docker compose. N’installez pas le paquet docker-compose d’Ubuntu 24.04 pour faire disparaître le message : c’est la v1 1.29.2.

« docker: unknown command: docker compose »

docker: unknown command: docker compose

Run 'docker --help' for more information

Docker est installé, mais pas le plugin Compose. Installez docker-compose-plugin (tableau des distributions plus haut).

« permission denied while trying to connect to the docker API »

permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

Votre compte n’a pas le droit de piloter Docker. Lancez la commande avec sudo, ou ajoutez votre compte au groupe docker en suivant notre guide Installer Docker sur Linux, qui explique aussi pourquoi ce groupe donne l’équivalent des droits root.

Comment ces commandes ont été vérifiées

Deux niveaux : Testé signifie que la commande a été exécutée sur un vrai système et son résultat observé ; Documentation signifie qu’elle a été vérifiée dans la documentation officielle, sans exécution, avec un lien vers la source.

Voir le détail des 21 vérifications
Élément Niveau Où et comment
Arborescence, compose.yaml, .env, docker compose config (sortie identique à celle publiée), config -q, config --environment et priorité d’une variable du shell, up -d, ps, logs, exec, ls, équivalent docker run ; page servie Testé Debian 13 (Docker Engine 29.9.0, Compose 5.6.0 du dépôt Docker, image officielle nginx:1.30-alpine) ; banc Ubuntu 24.04
Mise à jour : up -d sans pull garde l’ancienne image (Nginx 1.29.8 resté en place sous le tag 1.30-alpine), pull puis up -d recrée le conteneur en 1.30.5, up -d sans changement ne recrée rien ; retour arrière par tag ou par empreinte (docker image inspect), image retéléchargée si absente ; docker image prune ne supprime que les images orphelines Testé Debian 13, Docker Hub ; banc avec registre local
Boucle de mise à jour sur compose.yaml et docker-compose.yml, .env lu via -f, arrêt de up -d si pull échoue, copie de sauvegarde prise pour un service Testé Debian 13 ; banc Ubuntu 24.04
Sauvegarde tar service arrêté, restauration, comparaison diff -r identique ; archive rendue à votre compte par chown puis chmod 600 (illisible par votre compte sans le chown) ; suppression de l’ancien dossier refusée sans sudo quand il contient un dossier de root Testé Debian 13 ; banc Ubuntu 24.04, compte ordinaire avec sudo
Volume nommé : docker volume inspect (et son erreur sur un nom faux), archive avec alpine, contrôle tar -tzf, restauration dans un volume neuf Testé Banc Ubuntu 24.04 ; Debian 13 pour l’archive avec alpine
restart: unless-stopped : relance après plantage, pas de relance après stop puis redémarrage de Docker, relance après redémarrage de Docker Testé Debian 13 : plantage simulé (kill -9) puis redémarrage réel du PC, service unless-stopped relancé, service arrêté à la main et service sans politique restés arrêtés ; banc Ubuntu 24.04 (redémarrage du démon Docker)
depends_on : forme courte sans attente de la base ; condition: service_healthy qui attend l’état healthy ; message dependency failed to start ; après un redémarrage de Docker, application lancée sans attendre la base puis relancée par restart: unless-stopped ; $$ transmis tel quel au conteneur ; bloc PostgreSQL de l’article lancé tel quel : fichier valide, base déclarée healthy par pg_isready (« accepting connections »), application démarrée seulement ensuite Testé Banc Ubuntu 24.04 : services alpine simulant une base lente, puis image construite avec PostgreSQL 16 d’Ubuntu sous le nom postgres:18 (pas l’image officielle)
Volume nommé pré-rempli par l’image (index.html et 50x.html de l’image officielle), dossier vide qui masque l’image, dossier créé par Docker en root même pour un utilisateur ordinaire, down garde les volumes, down -v les supprime, emplacement /var/lib/docker/volumes ; volume anonyme perdu après down puis up -d Testé Debian 13 ; banc Ubuntu 24.04 (volume anonyme : banc seulement)
docker system prune -a --volumes garde les volumes nommés ; docker volume prune -a les supprime Testé Banc Ubuntu 24.04
Port publié joignable malgré UFW « deny incoming » ; port lié à 127.0.0.1 injoignable depuis une autre machine et depuis un conteneur proxy ; service sur un réseau proxy externe sans port publié, joint par un autre conteneur Testé Banc Ubuntu 24.04, UFW actif, client dans un espace de noms réseau séparé
docker compose run --rm ; expose: sans ports: : port non publié sur la machine Testé Banc Ubuntu 24.04
${WEB_PORT:?…} bloque le lancement ; variable absente sans :? : simple avertissement et port aléatoire ; mot de passe avec $ tronqué sans guillemets, transmis tel quel entre guillemets simples Testé Banc Ubuntu 24.04
Messages d’erreur (fichier absent, port alloué, adresse déjà utilisée, version obsolète, docker-compose absent, plugin absent, docker.sock) Testé Banc Ubuntu 24.04
Service Docker activé au démarrage par le paquet Debian ; systemctl enable docker.service containerd.service ; mise à jour du plugin par apt ; paquet Debian docker-compose 2.26.1 ; paquets Ubuntu 24.04 docker-compose 1.29.2 (v1) et docker-compose-v2 2.40.3 Testé Banc Ubuntu 24.04 ; Debian 13
Versions de Compose et de Docker Engine ; recréation possible des conteneurs annoncée pour Compose 5.5.0 Documentation Notes de version de Compose, notes de version de Docker Engine
Historique v1, v2, v5 Documentation Docker
Paquets par distribution Documentation Docker, Debian, Ubuntu, Fedora, Arch, openSUSE
Politiques de redémarrage, syntaxe des ports, env_file et environment Documentation Référence des services Compose
Exemple PostgreSQL avec healthcheck et pg_isready, conditions de depends_on Documentation Docker
Interpolation du .env et priorités ; Docker et UFW Documentation Interpolation, pare-feu
Watchtower n’est plus maintenu Documentation Dépôt de Watchtower

Bancs de test, les 14 et 16 octobre 2026 : le PC de l’auteur sous Debian 13 (Docker Engine 29.9.0 et Compose 5.6.0 installés depuis le dépôt Docker, images officielles téléchargées depuis Docker Hub) ; un conteneur Ubuntu 24.04 (Docker Engine 29.8.2, Compose 5.6.0) pour les tests qui demandent de modifier le pare-feu, le démon ou le plugin. Sur ce second banc, les images venaient d’un registre local déclaré comme miroir de Docker Hub, construites à partir de Nginx 1.24 d’Ubuntu servant le même dossier sur le même port, et, pour PostgreSQL, de PostgreSQL 16 d’Ubuntu : le comportement de Compose y est celui testé, pas le contenu de l’image officielle.

FAQ

Docker Compose est-il obsolète ?

Non. Seule l’ancienne commande docker-compose (v1) l’est. Compose v5, appelé avec docker compose, est maintenu par Docker et publie une version presque chaque mois.

Docker Compose ou Kubernetes pour un serveur maison ?

Docker Compose. Kubernetes sert à répartir des services sur plusieurs machines et à les maintenir disponibles si l’une tombe. Pour quelques services sur un seul serveur, il ajoute une complexité que rien ne justifie.

Portainer remplace-t-il Docker Compose ?

Non, il s’appuie dessus : les « stacks » de Portainer sont des fichiers Compose. Portainer ajoute une interface web pour les gérer, utile pour surveiller l’état des conteneurs ; notre guide pour installer Portainer le déploie justement avec Compose.

Peut-on utiliser des fichiers Compose avec Podman ?

Oui. La commande podman compose lance un outil Compose externe, docker-compose ou podman-compose, en le faisant communiquer avec Podman. Vos fichiers compose.yaml restent donc utilisables.

Faut-il nommer le fichier compose.yaml ou docker-compose.yml ?

compose.yaml est le nom recommandé aujourd’hui. Compose lit aussi compose.yml, docker-compose.yaml et docker-compose.yml : inutile de renommer un fichier existant.

Conclusion

Pour héberger vos services sous Linux, écrivez chaque service dans son propre dossier avec un compose.yaml et un .env, figez les images sur une branche plutôt que sur latest, et vérifiez le fichier avec docker compose config avant chaque lancement. Mettez à jour avec pull puis up -d, jamais sans sauvegarde récente pour les applications qui ont une base de données. Et ne publiez un port que lorsqu’un navigateur doit réellement l’atteindre : UFW ne le protégera pas. Derrière un reverse proxy installé dans Docker, ne publiez rien et passez par un réseau commun.

Pour choisir les services à installer avec Compose, notre guide pour monter un homelab propose un ordre et un tutoriel pour chacun ; si Docker n’est pas encore sur votre machine, commencez par installer Docker sur Linux.

Sources officielles

Vincent

Vincent est le créateur de MémoLinux. Il y documente les commandes, l’installation et la configuration des distributions Linux, du poste de travail au serveur maison. Il teste les commandes sur ses machines ou dans des environnements de test quand c’est possible, et s’appuie sinon sur la documentation officielle, qu’il cite. Les articles récents indiquent, pour chaque point, ce qui a été testé et sur quel système.

Laisser un commentaire