Docker v29 sur VPS : migration sans casser vos stacks

Sur chaque VPS à auditer, exécutez les deux commandes suivantes :

docker version --format '{{.Client.APIVersion}}'
docker version --format '{{.Server.APIVersion}}'

Si la version client est inférieure à 1.44 et que le daemon tourne en v29, vous obtenez une erreur lors des prochaines commandes. Le seuil 1.44 est le minimum accepté par Docker Engine v29 : un client compilé pour 1.43 ou antérieur échoue avec Error response from daemon: client version 1.43 is too old. Minimum supported API version is 1.44, please upgrade your client.

Si les deux lignes affichent 1.44 ou plus, votre client est compatible. Passez à l'étape suivante.

La commande docker-compose avec tiret et la commande docker compose sans tiret ne sont pas la même chose. Le v1 est un binaire Python autonome, le v2 est un plugin Go intégré au CLI Docker.

which docker-compose && docker-compose --version

Si la commande retourne un chemin dans /usr/local/bin/ ou /usr/bin/ avec une version 1.x.x, vous avez le binaire standalone déprécié. Après la mise à jour Docker v29, ce binaire renvoie docker-compose: command not found si le paquet a été retiré, ou l'erreur d'API décrite ci-dessus s'il est encore présent.

docker compose version

Si cette commande renvoie Docker Compose version v2.x.x, le plugin v2 est déjà présent. Les deux peuvent coexister temporairement, mais l'objectif est de n'utiliser que le plugin v2.

apt remove docker-compose
apt install docker-compose-plugin

Sur un VPS Debian ou Ubuntu qui utilise les dépôts officiels Docker Inc. (download.docker.com), le paquet docker-compose-plugin est disponible sans configuration supplémentaire. Si apt remove docker-compose répond Package not found, le binaire a été installé manuellement : localisez-le avec which docker-compose et supprimez le fichier.

Vérification post-migration :

docker compose version
# Docker Compose version v2.36.0

La grande majorité des fichiers docker-compose.yml écrits pour v1 fonctionnent sans modification avec le plugin v2. Les seules ruptures de syntaxe concernent les directives version: supérieures à "3.8" (ignorées en v2, pas bloquantes) et l'option --compatibility (retirée). Validez vos fichiers existants :

docker compose config

Cette commande résout les variables d'environnement, valide la syntaxe et affiche la configuration résolue. Une sortie sans erreur signifie que votre fichier est compatible.

Si votre équipe utilise des scripts shell avec docker-compose (tiret), posez un alias de compatibilité dans /etc/bash.bashrc du VPS :

alias docker-compose='docker compose'

Cet alias ne résout pas les scripts qui appellent docker-compose en absolu dans un cron ou un service systemd — auditez-les.

La bonne nouvelle : docker network fonctionne correctement avec nftables. Le trafic entre conteneurs, la NAT et l'exposition de ports continuent de fonctionner. Ce qui change, c'est l'outil sous-jacent qui écrit les règles.

docker network ls

Vos réseaux bridge existants sont toujours listés. Pour vérifier qu'un conteneur reçoit bien du trafic sur le port attendu, testez directement :

curl -s http://localhost:8080/health

Si la réponse est correcte, le plan de données Docker fonctionne indépendamment du backend.

Le problème se présente quand un script tiers (monitoring, Ansible, règles UFW) inspecte iptables pour vérifier que les règles Docker sont présentes :

iptables -L DOCKER 2>&1

Avec le backend nftables, cette chaîne est vide ou absente. Le script retourne une erreur alors que Docker fonctionne parfaitement. Ce n'est pas une panne Docker — c'est votre outil d'audit qui ne regarde plus au bon endroit.

Pour inspecter les règles réelles :

nft list ruleset | grep -A 20 'docker'

Si vos scripts de monitoring ou vos playbooks Ansible vérifient la présence de règles iptables spécifiques à Docker, adaptez-les pour interroger nftables plutôt que d'en déduire une panne.

Si vous avez des règles UFW personnalisées qui interagissent avec les règles Docker, consultez la documentation Docker sur le mode DOCKER-USER — il existe en nftables comme en iptables, mais la syntaxe d'ajout de règles diffère. L'article [pare-feu-ufw-vps](/blog/pare-feu-ufw-vps) couvre UFW de manière générale ; pour l'interaction spécifique à Docker v29, référez-vous aux notes de release officielle.

docker info | grep 'Storage Driver'

Sur un VPS mis à jour vers v29 sans modification de configuration, vous obtenez typiquement Storage Driver: overlay2. Le magasin containerd est en opt-in sur v29 — il n'est pas activé automatiquement. Il deviendra le défaut sur v30.

Si vous voyez Storage Driver: overlayfs (signe que quelqu'un a déjà activé le backend containerd), le magasin est actif.

Pour activer le magasin containerd sur v29 et préparer la migration avant qu'elle ne soit imposée en v30, ajoutez la clé suivante dans /etc/docker/daemon.json :

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

Redémarrez le daemon :

systemctl restart docker

Vérification :

docker info | grep 'Storage Driver'
# Storage Driver: overlayfs

Point d'attention : les images existantes tirées sous overlay2 restent disponibles, mais les nouvelles couches sont écrites dans le format containerd. Si vous devez revenir en arrière, supprimez la clé et redémarrez — les images du nouveau format ne seront plus accessibles sans le backend containerd. C'est pourquoi un snapshot avant cette étape est conseillé.

Cause : le binaire docker-compose v1 standalone est encore présent et tente de communiquer avec le daemon v29.

Remède :

apt remove docker-compose
apt install docker-compose-plugin
docker compose version

Si le binaire a été installé manuellement (hors apt), cherchez-le :

which docker-compose
rm /usr/local/bin/docker-compose

Cause : le paquet docker-compose (v1) a été retiré lors de la mise à jour, et le plugin v2 n'a pas été installé.

Remède :

apt install docker-compose-plugin

Vérifiez ensuite que vos scripts qui appellent docker-compose (avec tiret) utilisent désormais docker compose (sans tiret), ou posez l'alias système.

Cause : votre script inspecte la chaîne DOCKER dans iptables, mais Docker v29 avec nftables ne l'écrit plus là.

Remède : remplacez la vérification iptables par une vérification nftables :

nft list ruleset | grep -c 'docker'

Si le count est supérieur à zéro, les règles Docker sont présentes en nftables. Ou utilisez docker network inspect bridge pour vérifier l'état du plan de données directement depuis Docker, sans dépendre du backend réseau.

Cause : Dockge 1.4.1 et antérieurs appellent des routes d'API absentes de Docker Engine v29.

Remède :

cd /opt/dockge
docker compose pull
docker compose up -d

Si le tag latest de l'image Dockge est déjà en 1.4.2 ou supérieur, cette commande suffit. Sinon, éditez votre docker-compose.yml Dockge pour pointer vers le tag de la version corrective avant de relancer.

Cause : lors du premier redémarrage de dockerd en mode nftables, les règles de NAT sont réécrites dans le bon backend, mais certaines distributions ont un conflit entre le service iptables-legacy et nftables qui retarde la mise en place des règles.

Remède :

systemctl stop docker
systemctl disable iptables
systemctl start docker

Puis vérifiez que les conteneurs sont bien redémarrés (docker compose up -d) et que les ports sont exposés (`docker ps --format 'table {{.Names}}\t{{.Ports}}').