Debian 12 auf 13 upgraden mit Docker: docker-compose vs. docker compose

Komplettes Praxis-Tutorial für Docker auf Debian 12 → 13: Compose V1 vs. V2, docker-compose vs. docker compose, Paketquellen, Skripte, Backups und sichere Migration.

Warum dieser Unterschied beim Debian-Upgrade wichtig ist

Beim Wechsel von Debian 12 Bookworm auf Debian 13 Trixie kann Docker selbst weiter funktionieren, während sich die Compose-Befehle und die Herkunft der Compose-Installation ändern. Genau hier entsteht die typische Überraschung: Auf dem alten System funktioniert `docker-compose`, auf dem neuen System ist plötzlich nur noch `docker compose` vorhanden – oder ein altes Skript findet das Kommando nicht mehr.

Die kurze Antwort: Docker Compose ist heute ein Docker-Plugin

Bei aktuellen Docker-Installationen ist Compose V2 als CLI-Plugin Bestandteil des Docker-Ökosystems. Die moderne Schreibweise lautet `docker compose`, also mit einem Leerzeichen. Debian 13 Trixie stellt ebenfalls ein Paket `docker-compose` bereit, das Compose V2 enthält. Der Paketname ist deshalb nicht mit dem historischen Compose V1 gleichzusetzen.

docker-compose vs. docker compose – was ist der Unterschied?

Historisch war `docker-compose` ein eigenständiges Programm. Compose V1 wurde als separates Python-Tool ausgeliefert. Compose V2 wurde in Go neu implementiert und als Docker-CLI-Plugin integriert. Deshalb ist `docker compose` heute die bevorzugte Form. Der sichtbare Unterschied ist nur ein Leerzeichen, technisch steckt aber eine andere Architektur dahinter.

Warum Debian 12 → Debian 13 so eine Falle sein kann

Auf Debian 12 können ältere Installationen noch aus einem Paket, einer manuellen Installation oder einem früher eingerichteten Docker-Repository stammen. Debian 13 bringt eine andere Paketlandschaft mit. Wer nach dem Upgrade nur `docker --version` prüft, kann übersehen, dass ein separates `docker-compose`-Binary verschwunden ist.

Vor dem Upgrade: zuerst den Ist-Zustand dokumentieren

Bevor du Debian aktualisierst, solltest du festhalten, wie Docker installiert ist und welche Compose-Variante tatsächlich verwendet wird.

docker --version
docker compose version
docker-compose --version
which docker
which docker-compose
docker compose ls
docker ps -a
dpkg -l | grep -E 'docker|containerd|compose'

Der wichtigste Test: beide Compose-Befehle prüfen

Führe vor dem Upgrade bewusst beide Varianten aus. Wenn `docker compose version` eine Version liefert, ist Compose V2 vorhanden. Wenn zusätzlich `docker-compose --version` funktioniert, existiert noch ein separates Kommando. Genau diese Information entscheidet darüber, ob alte Skripte und Cronjobs angepasst werden müssen.

Compose-Dateien müssen meistens nicht neu geschrieben werden

Der Wechsel von Compose V1 zu V2 bedeutet nicht automatisch, dass deine `compose.yml` neu geschrieben werden muss. Compose V2 verwendet weiterhin das Compose-Dateiformat. Ein sehr nützlicher Test ist `docker compose config`, weil Docker dabei die Datei einliest und die aufgelöste Konfiguration ausgibt.

Der Klassiker: Skripte mit docker-compose

Besonders gefährlich sind Shell-Skripte, systemd-Units, Cronjobs, Deployment-Skripte und Backups, in denen hart `docker-compose` steht. Nach dem Upgrade kann `docker compose up -d` funktionieren, während ein automatisches Skript mit `docker-compose: command not found` scheitert.

So findest du alte Aufrufe

Für ein Projektverzeichnis reicht beispielsweise `grep -RIn --exclude-dir=.git 'docker-compose' /pfad/zum/projekt`. Nicht blind jede Fundstelle ersetzen: Prüfe zuerst, ob es ein echtes Kommando, Dokumentation oder ein Dateiname ist.

grep -RIn --exclude-dir=.git 'docker-compose' /pfad/zum/projekt

Migration: docker-compose durch docker compose ersetzen

Die üblichen Befehle lassen sich direkt umstellen: `docker-compose up -d` wird zu `docker compose up -d`, `docker-compose down` zu `docker compose down`, `docker-compose pull` zu `docker compose pull`, `docker-compose logs -f` zu `docker compose logs -f` und `docker-compose exec web bash` zu `docker compose exec web bash`. Die Compose-Datei bleibt normalerweise unverändert.

Was ist mit docker-compose.yml?

Der Dateiname `docker-compose.yml` kann in bestehenden Projekten weiterhin vorkommen. Das ist nicht dasselbe Problem wie der alte Befehl. Moderne Compose-Projekte verwenden häufig `compose.yaml` oder `compose.yml`; bestehende Dateien mit älteren Namen können weiterhin funktionieren.

Installation auf Debian 13

Wenn Docker aus dem offiziellen Docker-Repository installiert wird, dokumentiert Docker für Debian die Installation von `docker-ce`, `docker-ce-cli`, `containerd.io`, `docker-buildx-plugin` und `docker-compose-plugin`. Debian 13 selbst bietet außerdem ein Paket `docker-compose`, das Compose V2 enthält. Bei einer bestehenden Serverinstallation sollte man sich bewusst für eine Paketquelle entscheiden und nicht mehrere Installationswege vermischen.

Achtung bei docker.io und Docker CE

Docker weist ausdrücklich darauf hin, dass Pakete wie `docker.io`, `docker-compose`, `docker-doc`, `docker-buildx` oder `podman-docker` mit den offiziellen Docker-Paketen kollidieren können. Vor einer Neuinstallation oder Migration sollte deshalb geprüft werden, welche Variante tatsächlich installiert ist.

Was passiert mit Containern, Images und Volumes?

Das Ändern oder Entfernen der Compose-Installation bedeutet nicht automatisch, dass Docker-Daten verschwinden. Docker dokumentiert, dass beim Entfernen der Docker-Pakete Images, Container und Volumes unter `/var/lib/docker/` nicht automatisch gelöscht werden. Trotzdem sollte vor einem Betriebssystem-Upgrade immer ein echtes Backup wichtiger Volumes und Konfigurationsdateien vorhanden sein.

Der sichere Ablauf für Debian 12 → Debian 13

Ein pragmatischer Ablauf: 1. Docker- und Compose-Versionen dokumentieren. 2. Container und Volumes erfassen. 3. Compose-Dateien und `.env` sichern. 4. Skripte auf `docker-compose` prüfen. 5. Docker-Paketquelle dokumentieren. 6. Debian-Upgrade durchführen. 7. Docker-Dienst prüfen. 8. `docker compose version` testen. 9. Projekte mit `docker compose config` validieren. 10. Erst danach Container mit `docker compose up -d` starten.

Nach dem Upgrade: die wichtigsten Prüfungen

Prüfe `systemctl status docker`, danach `docker info`, `docker compose version`, `docker ps -a` und für jedes Projekt `docker compose config`. Anschließend Logs kontrollieren. Ein Container mit Status `Up` ist noch kein Beweis, dass die Anwendung funktioniert.

systemctl status docker
docker info
docker compose version
docker ps -a
docker compose config

systemd, Cron und Automatisierung nicht vergessen

Viele Serverprobleme entstehen erst bei Automatisierungen. Prüfe systemd-Units, Timer, Cronjobs, Backupskripte und Monitoring-Skripte. Ein Dienst, der bisher `/usr/bin/docker-compose` aufgerufen hat, kann nach der Umstellung ins Leere zeigen.

Was ich heute verwenden würde

Auf einem neuen Debian-13-Server würde ich grundsätzlich `docker compose` verwenden und die Compose-Integration über das Docker-Compose-Plugin beziehungsweise eine konsistente Paketquelle installieren. Bei bestehenden Systemen würde ich zuerst den Ist-Zustand prüfen und dann kontrolliert auf Compose V2 umstellen.

Meine Debian-Upgrade-Checkliste

Vor dem Upgrade: `docker --version`, `docker compose version`, `docker-compose --version`, `docker ps -a`, `docker volume ls`, `docker network ls`, `dpkg -l | grep -E 'docker|containerd|compose'`, Suche nach `docker-compose` in Skripten und Backup der Compose-Dateien und wichtigen Volumes. Danach Docker-Dienst, Compose, Konfiguration, Container und Logs prüfen.

Fazit

Der eigentliche Stolperstein beim Wechsel von Debian 12 auf Debian 13 ist nicht, dass Docker plötzlich unbrauchbar wird. Häufiger ändert sich die Compose-Installation: Aus dem alten separaten `docker-compose` wird das moderne `docker compose` als Docker-CLI-Plugin. Wer vor dem Upgrade Versionen, Paketquellen, Skripte und Automatisierungen prüft, erspart sich die klassische Überraschung nach dem Reboot.

docker --version
docker compose version
docker-compose --version
docker ps -a
docker volume ls
docker network ls
dpkg -l | grep -E 'docker|containerd|compose'