Installer Docker et Docker Compose sur Debian et Ubuntu

Installer Docker prend cinq minutes. Installer Docker de façon à ce que le serveur reçoive encore des mises à jour de sécurité un an plus tard, que le disque système ne se remplisse pas et qu'aucun utilisateur ne se promène par mégarde avec les droits root, prend un peu plus longtemps. Cet article traite de la seconde approche, vérifiée sur Debian 13 (Trixie), Debian 12 (Bookworm), Ubuntu 24.04 (Noble) et Ubuntu 22.04 (Jammy).

docker.io ou Docker CE : la différence que presque personne n'explique honnêtement

Il existe deux façons d'obtenir Docker. Le paquet docker.io provient des dépôts de la distribution et il est construit et maintenu par Debian ou Ubuntu. Le paquet docker-ce provient du dépôt de Docker lui-même. Les deux contiennent le même logiciel, mais dans des versions d'âge très différent.

Voici les versions actuellement présentes dans les dépôts des distributions, mesurées avec apt-cache policy dans des conteneurs (containers) neufs :

C'est là que se trouve le vrai sujet, et presque tous les tutoriels le réduisent à une recommandation valable partout. La réalité est plus nuancée :

• Ubuntu 24.04 et 22.04 : docker.io est en 29.1.3, donc pratiquement au niveau de la version upstream actuelle. Si vous n'avez pas d'exigences particulières, vous pouvez prendre le paquet de la distribution sans mauvaise conscience. Les mises à jour de sécurité arrivent alors par le canal Ubuntu habituel.
• Debian 13 : 26.1.5 reste utilisable, mais accuse un net retard sur l'upstream. Pour la plupart des cas d'usage, cela suffit.
• Debian 12 : 20.10.24 est le cas problématique. Cette branche est en fin de vie depuis des années côté upstream. Debian y intègre certes les correctifs de sécurité, mais beaucoup de fonctions modernes manquent tout simplement, entre autres une version récente de BuildKit et une bonne partie de la compatibilité Compose.

S'y ajoute une différence pratique : docker-ce livre Buildx et Compose sous forme de paquets de plugins distincts, accordés à la version du moteur. Avec docker.io, vous devez rassembler ces morceaux séparément depuis docker-buildx et docker-compose-v2, et docker-compose-v2 n'existe que dans les dépôts Ubuntu : sous Debian, ce paquet n'existe pas du tout.

Ce qui ne fonctionne pas : les deux en parallèle. Le paquet containerd.io du dépôt Docker entre en conflit avec le paquet containerd de la distribution. Vous devez trancher.

Règle empirique : sous Ubuntu, docker.io est un choix légitime. Sous Debian 12, non. Pour les serveurs qui font tourner des stacks Compose avec une syntaxe récente, Docker CE reste partout la meilleure décision.

Supprimer les anciens paquets avant toute autre chose

Si un Docker est déjà présent sous une forme ou une autre, il doit disparaître, sinon l'installation échouera sur des conflits de paquets. La boucle suivante retire tous les suspects habituels et absorbe au passage les paquets qui ne sont pas installés ou qui n'existent pas du tout dans votre distribution :

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove -y $pkg || true; done

Le || true dans le corps de la boucle n'est pas un détail cosmétique, il est nécessaire. Sous Debian, apt-get s'interrompt sur l'entrée docker-compose-v2 avec E: Unable to locate package docker-compose-v2 et un code de sortie 100, car ce paquet n'existe que dans les dépôts Ubuntu, ni dans bookworm ni dans trixie (ni dans bullseye, où podman-docker manque en plus). La boucle continue certes, mais elle laisse derrière elle un code de sortie différent de 0, et c'est exactement là que meurt un script avec set -e ou un enchaînement avec &&. Les messages du type « Unable to locate package » sont donc normaux à cet endroit et peuvent être ignorés, c'est aussi la position de la documentation officielle de Docker.

Bon à savoir : rien ne se perd au passage. Vos images, vos conteneurs et vos volumes se trouvent dans /var/lib/docker, et apt-get remove ne touche pas à ce répertoire. Après l'installation de Docker CE, vos conteneurs sont de nouveau là. Seul sudo rm -rf /var/lib/docker supprime réellement, et cela de manière irréversible.

Déposer la clé au bon endroit : apt-key appartient au passé

Beaucoup de tutoriels sur le web contiennent encore cette ligne :

curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -

Cela n'a plus vraiment de sens sur aucun des quatre systèmes traités ici. apt-key est déprécié et n'est même plus présent sur Debian 13. La raison n'est pas cosmétique : une clé placée dans /etc/apt/trusted.gpg signe tous les dépôts, pas seulement celui auquel elle était destinée. Un serveur miroir compromis pourrait ainsi vous glisser n'importe quel paquet.

La bonne méthode passe par un trousseau dédié sous /etc/apt/keyrings/, rattaché à une seule source via Signed-By.

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings

La commande suivante récupère la clé qui convient et fonctionne aussi bien sous Debian que sous Ubuntu, car elle lit l'identifiant de la distribution dans /etc/os-release :

sudo curl -fsSL "https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")/gpg" -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

Et maintenant l'étape que pratiquement personne ne décrit : vérifiez l'empreinte avant de confier votre système à cette clé.

gpg --show-keys /etc/apt/keyrings/docker.asc

La sortie doit contenir l'empreinte 9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88 et l'identité Docker Release (CE deb) <docker@docker.com>. Si cela ne correspond pas, arrêtez tout. C'est que quelque chose ne va pas avec votre connexion ou avec la source.

Installer Docker CE avec un seul bloc pour les quatre systèmes

La documentation officielle présente des blocs séparés pour Debian et pour Ubuntu. C'est inutile. Le bloc suivant écrit la source de paquets au format moderne deb822 et détermine lui-même la distribution, le nom de code et l'architecture :

sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

Deux détails qui font gagner du temps. Premièrement ${UBUNTU_CODENAME:-$VERSION_CODENAME} : sur les dérivés d'Ubuntu comme Linux Mint, VERSION_CODENAME contient le nom de la dérivée, pas celui d'Ubuntu. Deuxièmement la ligne Architectures : sans elle, apt se plaint sur les systèmes où l'architecture étrangère i386 est activée, avec un long avertissement au sujet de listes de paquets inexistantes.

Contrôlez le résultat avant de poursuivre :

cat /etc/apt/sources.list.d/docker.sources

La ligne Suites doit contenir trixie, bookworm, noble ou jammy. Si autre chose s'y trouve, l'étape suivante partira en erreur. Viennent ensuite la mise à jour et l'installation :

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Les cinq paquets sont : le démon, l'outil en ligne de commande, le runtime de conteneurs, le constructeur d'images moderne et Compose.

Comment savoir que tout tourne vraiment

Le fait que apt-get se soit terminé sans erreur signifie seulement que des fichiers sont posés sur le disque. Les quatre vérifications suivantes montrent si le système travaille réellement.

Premièrement : le client atteint-il le démon ?

docker version

Ce qui compte n'est pas la section Client, mais le fait qu'une section Server: Docker Engine - Community apparaisse en dessous avec un numéro de version. Si elle manque, soit le démon ne tourne pas, soit vous n'avez pas le droit d'accéder au socket.

Deuxièmement : quel pilote de stockage est actif ?

docker info --format '{{.Driver}}'
docker info --format '{{.CgroupVersion}}'

Une nouveauté se cache ici, à laquelle beaucoup de tutoriels plus anciens répondent de travers. Depuis Docker Engine 29, le magasin d'images containerd est activé par défaut pour les nouvelles installations. Le pilote s'appelle alors overlayfs et non plus overlay2. Les deux valeurs sont correctes. Ce que vous ne voulez pas voir, c'est vfs : ce pilote de secours copie intégralement chaque couche, dévore plusieurs fois plus d'espace disque et se traîne péniblement. Il apparaît typiquement quand Docker tourne dans un environnement dépourvu du support noyau adapté. La version de cgroup doit valoir 2 sur les quatre systèmes.

Si vous avez mis à jour un système existant et que toutes les images semblent soudain avoir disparu : elles ne sont pas supprimées. Lors du changement de magasin d'images, le contenu de l'autre emplacement est seulement masqué et réapparaît dès que vous revenez en arrière. Ce retour en arrière se règle dans /etc/docker/daemon.json :

{
  "features": {
    "containerd-snapshotter": false
  }
}

Troisièmement : un conteneur démarre-t-il vraiment ?

docker run --rm hello-world

Quatrièmement : le réseau et la résolution de noms fonctionnent-ils dans le conteneur ? Ce test manque dans presque tous les tutoriels, alors que c'est précisément là que naissent la plupart des problèmes ultérieurs :

docker run --rm alpine:3 ping -c 2 1.1.1.1
docker run --rm alpine:3 nslookup deb.debian.org

Si le ping répond mais que la résolution de noms échoue, la cause est le plus souvent un serveur DNS qui n'écoute que sur 127.0.0.53. Cette adresse n'est pas joignable depuis le conteneur. Le remède consiste à ajouter dans /etc/docker/daemon.json une entrée "dns": ["9.9.9.9"], puis à redémarrer le démon.

Compose est un plugin, ce n'est plus un programme à part

L'ancien docker-compose avec un tiret était un programme Python distinct. Il est arrivé en fin de vie et n'est plus livré. Le successeur est un plugin écrit en Go, appelé comme sous-commande de la CLI Docker, donc docker compose avec un espace.

docker compose version

Une remarque sur le numéro de version, parce que cela sème régulièrement la confusion : l'expression « Compose V2 » désigne la réécriture en Go, pas le numéro de version. La sortie affiche aujourd'hui une version de la branche 5. C'est correct, il ne s'agit pas d'un autre produit.

Deux choses sautent aux yeux lors du passage. D'une part, la clé version: au début de docker-compose.yml est devenue superflue et provoque un avertissement :

WARN[0000] docker-compose.yml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion

Supprimez simplement cette ligne. D'autre part, le nommage change : Compose déduit le nom du projet du nom du répertoire et crée des conteneurs avec un tiret au lieu d'un tiret bas, donc monprojet-web-1 au lieu de monprojet_web_1. Les scripts qui s'adressent aux conteneurs par des noms figés cassent à cause de cela. Dans ces situations, fixez explicitement le nom du projet via name: dans le fichier Compose ou via -p.

Si vous voulez délibérément rester sur les paquets de la distribution, le paquet qui convient s'appelle docker-compose-v2 et fournit la même sous-commande. Il n'est toutefois disponible que dans les dépôts Ubuntu. Vérifiez au préalable la version disponible :

apt-cache policy docker-compose-v2

Sous Ubuntu 24.04 et 22.04, un tableau apparaît avec la version installée et la version candidate. Sous Debian 13 et Debian 12, la commande n'affiche rien du tout, une sortie vide avec un code de sortie 0. Ce n'est pas une erreur, c'est la réponse : sous Debian, ce paquet n'existe pas, et le chemin vers Compose passe par docker-compose-plugin du dépôt Docker.

Le groupe docker, c'est root avec un détour

Pour qu'un utilisateur normal puisse se servir de Docker sans sudo, on l'ajoute habituellement au groupe docker :

sudo groupadd -f docker
sudo usermod -aG docker $USER

L'appartenance au groupe ne prend effet qu'à la prochaine connexion. Vous pouvez le contrôler après vous être reconnecté avec id -nG. Si vous ne voulez pas vous reconnecter, newgrp docker ouvre un shell doté du nouveau groupe.

Voici maintenant la partie que vous devez avoir comprise : appartenir au groupe docker équivaut à disposer des droits root sur l'ensemble du serveur. Ce n'est pas une appréciation théorique, c'est une conséquence directe du fonctionnement. Qui a le droit de parler au socket Docker a le droit de donner n'importe quel ordre au démon, lequel tourne en root. Une seule commande suffit :

docker run -it -v /:/hostfs alpine:3 chroot /hostfs sh

Le résultat est un shell root sur le système hôte, sans sudo, sans demande de mot de passe, sans trace dans la journalisation de sudo. Lire /etc/shadow, déposer des clés SSH, remplacer des services : tout devient possible. La documentation de Docker le formule brièvement et sans ambiguïté : « The docker group grants root-level privileges to the user. »

Conséquences pratiques pour un serveur exposé sur Internet :

• N'ajoutez au groupe que des comptes auxquels vous confieriez de toute façon les droits root.
• L'utilisateur sous lequel tourne une application web ou un runner CI n'en fait pas partie. Sinon, une intrusion dans l'application deviendrait automatiquement une intrusion dans le serveur.
• Si vous avez besoin de traçabilité, renoncez au groupe et appelez Docker via sudo docker. L'appel apparaîtra au moins dans le journal.
• Pour une séparation réelle, il existe le mode rootless. Il se met en place avec le paquet docker-ce-rootless-extras et l'outil dockerd-rootless-setuptool.sh install, et réclame en plus uidmap. Le prix à payer : les ports inférieurs à 1024 ne peuvent pas être occupés sans configuration supplémentaire, et certaines fonctions réseau se comportent différemment.

Démarrage automatique : le piège s'appelle docker.socket

La commande standard est connue :

sudo systemctl enable --now docker.service
sudo systemctl enable --now containerd.service

Ce qui est moins connu, c'est pourquoi la désactivation reste souvent sans effet. À côté de docker.service, Docker installe aussi une unité docker.socket. Celle-ci écoute sur le socket et démarre le démon automatiquement au premier accès. Si vous exécutez systemctl disable docker.service et constatez ensuite que Docker tourne malgré tout, vous n'avez pas vu de fantôme : le premier docker ps a relancé le démon via l'unité socket. Une désactivation complète réclame les deux :

sudo systemctl disable --now docker.service docker.socket

L'état se contrôle avec systemctl is-enabled docker.service, qui doit afficher enabled.

Le deuxième point concerne vos conteneurs. Ce n'est pas systemd qui décide si un conteneur revient après un redémarrage, mais la politique de redémarrage. Et là se cache une différence qui surprend régulièrement : always relance un conteneur même si vous l'aviez arrêté volontairement avant le redémarrage. unless-stopped respecte votre arrêt manuel au-delà du redémarrage. Pour un serveur, unless-stopped est en règle générale le bon choix :

services:
  web:
    image: nginx:stable
    restart: unless-stopped

Le test qui compte n'est pas docker ps, mais un véritable redémarrage du serveur suivi d'un contrôle.

Rotation des journaux : la cause la plus fréquente de disque système plein

Par défaut, Docker écrit la sortie de chaque conteneur dans un fichier JSON sous /var/lib/docker/containers/. Ce fichier grandit sans limite avec la configuration d'origine. Un reverse proxy bavard peut ainsi accumuler des dizaines de gigaoctets en quelques mois, jusqu'à ce que le serveur s'arrête sur no space left on device. Le coupable est alors difficile à trouver, car du ne montre rien de suspect dans le répertoire de l'application.

La solution a sa place sur chaque serveur, et cela avant l'apparition du premier problème :

sudo mkdir -p /etc/docker

sudo tee /etc/docker/daemon.json > /dev/null <<'EOF'
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
EOF

Si un fichier daemon.json existe déjà, cette commande l'écrase. Regardez d'abord ce qu'il contient et ajoutez les clés à la main le cas échéant. Ensuite :

sudo systemctl restart docker

Trois points sur lesquels cela peut malgré tout mal tourner :

• Les valeurs doivent être des chaînes de caractères entre guillemets. "max-file": 3 sans guillemets empêche le démon de démarrer.
• Le réglage ne vaut que pour les conteneurs nouvellement créés. Les conteneurs existants gardent leur ancienne configuration jusqu'à leur recréation, donc avec Compose via docker compose up -d --force-recreate.
• Supprimer avec rm un fichier journal qui a débordé ne rend aucun espace disque, car le démon garde le fichier ouvert. Utilisez plutôt sudo truncate -s 0 <chemin>.

Pour vérifier que le réglage s'applique bien à un conteneur précis :

docker inspect --format '{{json .HostConfig.LogConfig}}' monconteneur

Faire le ménage avec docker system prune sans perdre de données

Les images inutilisées, les builds interrompus et le cache BuildKit s'additionnent. Commencez par regarder où part l'espace :

docker system df
docker system df -v

La commande de nettoyage par défaut supprime les conteneurs arrêtés, les réseaux inutilisés, les images sans nom et le cache de build :

docker system prune

Deux options méritent le respect. -a supprime en plus toutes les images qui ne sont utilisées par aucun conteneur à cet instant, y compris des images de base soigneusement entretenues. Sur un serveur à connexion étroite, le rechargement peut ensuite prendre du temps. Nettement plus dangereuse est l'option --volumes : elle retire les volumes nommés qui n'ont plus de conteneur associé. Si votre conteneur de base de données vient d'être supprimé alors que le volume contient encore les données, celles-ci disparaissent. Il n'y a pas de corbeille.

N'utilisez jamais --volumes dans une tâche de nettoyage automatique.

Un délai de grâce est judicieux, pour que seul le matériel réellement ancien disparaisse :

docker system prune -a --filter "until=168h"
docker builder prune --filter "until=168h"

Comme tâche hebdomadaire, exécutée la nuit pour ménager les ressources et sans suppression de volumes, une seule ligne dans /etc/cron.d/docker-prune suffit :

15 4 * * 0 root /usr/bin/docker system prune -af --filter "until=168h" > /dev/null 2>&1

La preuve du succès est un nouveau docker system df dont la colonne « RECLAIMABLE » a baissé.

Les messages d'erreur mot pour mot et ce qui se cache derrière

permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock
L'utilisateur n'est pas dans le groupe docker, ou son appartenance au groupe n'est pas encore active dans la session courante. Reconnectez-vous ou passez par newgrp docker.

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
Le démon ne tourne pas. La cause et le message exact viennent de systemctl status docker et, plus en détail, de journalctl -u docker -n 50 --no-pager. Très souvent, une /etc/docker/daemon.json défectueuse se cache derrière. Ce fichier doit être du JSON valide, une seule virgule en trop suffit.

docker: 'compose' is not a docker command.
Le plugin manque. Installez soit docker-compose-plugin depuis le dépôt Docker, soit, uniquement sous Ubuntu, docker-compose-v2 depuis la distribution.

E: Conflicting values set for option Signed-By regarding source https://download.docker.com/linux/debian/ trixie: /etc/apt/keyrings/docker.asc != /etc/apt/keyrings/docker.gpg
Le grand classique après avoir enchaîné plusieurs tutoriels : une ancienne /etc/apt/sources.list.d/docker.list et la nouvelle docker.sources coexistent. Supprimez l'ancien fichier et relancez sudo apt-get update. Faites-vous une vue d'ensemble avec ls -l /etc/apt/sources.list.d/.

The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 8D81803C0EBFCD88
La clé ne se trouve pas là où Signed-By l'attend, ou le fichier téléchargé est incomplet (par exemple parce qu'un proxy a renvoyé une page d'erreur HTML). gpg --show-keys /etc/apt/keyrings/docker.asc montre immédiatement s'il contient bien une clé.

E: The repository 'https://download.docker.com/linux/debian trixie Release' does not have a Release file.
Le nom de code ne correspond pas à la source. Cela arrive sur les distributions dérivées et quand on mélange des tutoriels Debian et Ubuntu. Contrôlez les lignes URIs et Suites dans docker.sources.

Bind for 0.0.0.0:80 failed: port is already allocated
Un autre service occupe le port, souvent un serveur web installé directement sur l'hôte. sudo ss -tulpn | grep :80 désigne le responsable.

Docker et le pare-feu : un mot sur la sécurité

Une particularité qui peut coûter cher sur un serveur accessible publiquement : Docker inscrit ses règles de redirection dans la table NAT et contourne ainsi les règles que vous avez soigneusement entretenues dans ufw. Un conteneur démarré avec -p 5432:5432 est joignable depuis Internet, même si ufw status n'autorise ce port nulle part. Cela reste vrai bien que Docker Engine 28 ait durci le comportement réseau dans son ensemble et bloqué l'accès extérieur aux ports non publiés.

La contre-mesure la plus simple et la plus fiable consiste à lier explicitement à l'adresse de loopback les services dont vous n'avez besoin qu'en local :

services:
  db:
    image: postgres:17
    ports:
      - "127.0.0.1:5432:5432"
    restart: unless-stopped

Mieux encore : ne publiez pas du tout ces ports et laissez les conteneurs se parler via un réseau Docker commun. Le résultat se vérifie le plus sûrement depuis une seconde machine, car un test effectué depuis le serveur lui-même ne répond pas à la question décisive.

En résumé

Sous Debian 12, prenez impérativement Docker CE ; sous Ubuntu, vous pouvez choisir entre docker.io et Docker CE. Intégrez le dépôt avec un trousseau dédié et une empreinte vérifiée, pas avec apt-key. Utilisez docker compose avec un espace. Traitez le groupe docker comme un accès root, parce que c'est exactement ce qu'il est. Et mettez en place la rotation des journaux ainsi qu'une tâche de prune hebdomadaire avant que le serveur ne cale une première fois sur un disque plein.

Dans le même esprit : Configurer le pare-feu UFW sur Debian et Ubuntu et Installer Nginx sur Debian et Ubuntu.