Du willst mehrere Container mit einer einzigen Datei starten, statt seitenlange docker run-Befehle zu tippen? Dann führt kein Weg an Docker Compose vorbei. In dieser Anleitung zeigen wir dir, wie du Docker Compose unter Ubuntu und Debian installierst – und zwar die aktuelle Version 2 als offizielles Docker-Plugin. Am Ende schreibst du deine erste docker-compose.yml und kennst die wichtigsten Befehle.
Was ist Docker Compose?
Docker Compose ist ein Werkzeug, mit dem du mehrere Container gemeinsam als einen Stack definierst und verwaltest. Statt jeden Container einzeln zu starten, beschreibst du in einer YAML-Datei, welche Dienste laufen sollen, welche Images sie nutzen, welche Ports offen sind und welche Volumes eingebunden werden. Ein einziger Befehl startet dann das komplette Setup.
Das ist ideal für typische Selfhosting-Szenarien: eine Web-App plus Datenbank plus Reverse Proxy – alles in einer Datei, versionierbar und reproduzierbar. Wenn du noch ganz am Anfang stehst, lohnt sich vorab ein Blick auf unseren Grundlagenartikel Was ist Docker?.
Voraussetzungen
- Docker Engine ist installiert – Compose v2 setzt auf der Docker Engine auf. Wie du beides in einem Rutsch installierst, zeigen wir gleich.
- Ein Ubuntu- oder Debian-System (z. B. Ubuntu 22.04/24.04 oder Debian 12/13) mit
sudo– bzw. Root-Rechten. - Terminal-Zugang per SSH oder direkt an der Konsole.
Docker Compose installieren – das Plugin v2
Die empfohlene Methode ist die Installation über das offizielle Docker-APT-Repository. Dabei bekommst du die Docker Engine und das Compose-Plugin aus derselben Quelle und erhältst automatisch Updates.
1. Alte Pakete entfernen und Grundpakete installieren
Entferne zunächst eventuell vorhandene Distributionspakete, die veraltet sein können, und installiere die für HTTPS-Repositories nötigen Pakete:
# Alte / Distributions-Pakete entfernen (falls vorhanden)
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove -y $pkg; done
# Grundpakete
sudo apt-get update
sudo apt-get install -y ca-certificates curl2. Docker-GPG-Schlüssel hinterlegen
Lege das Keyring-Verzeichnis an und importiere den offiziellen Signaturschlüssel. Ersetze ubuntu durch debian, wenn du Debian nutzt:
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc3. Repository einbinden
Füge das Docker-Repository passend zu deiner Distribution und Architektur hinzu. Für Debian ersetzt du in der URL ubuntu durch debian:
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update4. Docker Engine und Compose-Plugin installieren
Jetzt installierst du die Engine samt Compose-Plugin. Das Paket docker-compose-plugin bringt den Befehl docker compose mit:
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin5. Installation prüfen
Kontrolliere zum Schluss die installierte Compose-Version:
docker compose version
# Beispielausgabe:
# Docker Compose version v2.x.xOptional kannst du deinen Benutzer zur Gruppe docker hinzufügen, um Compose ohne sudo auszuführen. Melde dich danach neu an:
sudo usermod -aG docker $USERdocker compose vs. docker-compose: V1 und V2 im Unterschied
Bei der Recherche stößt du auf zwei Schreibweisen. Der Unterschied ist wichtig:
docker-compose(mit Bindestrich) war die alte, in Python geschriebene Version 1. Sie wird nicht mehr weiterentwickelt und sollte für neue Projekte nicht mehr verwendet werden.docker compose(mit Leerzeichen) ist die aktuelle Version 2 als Plugin der Docker CLI. Sie ist schneller, wird gepflegt und ist das, was du oben installiert hast.
Falls du ältere Anleitungen mit docker-compose up findest: Ersetze den Bindestrich einfach durch ein Leerzeichen. Wer die alte Syntax aus Kompatibilitätsgründen dennoch braucht, kann zusätzlich das Paket docker-compose installieren – für Neuinstallationen ist das aber unnötig.
Deine erste docker-compose.yml
Zeit für ein praktisches Beispiel. Lege einen Projektordner an und darin eine Datei docker-compose.yml. Das folgende Setup startet einen Nginx-Webserver auf Port 8080:
services:
web:
image: nginx:latest
container_name: mein-webserver
ports:
- "8080:80"
volumes:
- ./html:/usr/share/nginx/html:ro
restart: unless-stoppedEin Hinweis am Rande: In Compose v2 ist die früher übliche erste Zeile version: "3" nicht mehr nötig und gilt als veraltet. Starte den Stack anschließend im selben Verzeichnis:
docker compose up -dDer Parameter -d (detached) startet die Container im Hintergrund. Rufe nun http://SERVER-IP:8080 im Browser auf – Nginx begrüßt dich. Solltest du dabei auf einen Fehler zur Volume-Definition stoßen, hilft dir unser Beitrag „service refers to undefined volume“ weiter.
Die wichtigsten Compose-Befehle
Diese Befehle brauchst du im Alltag am häufigsten. Führe sie immer im Verzeichnis mit deiner docker-compose.yml aus:
| Befehl | Wirkung |
|---|---|
docker compose up -d | Stack im Hintergrund starten (Container werden bei Bedarf gebaut/erstellt) |
docker compose down | Stack stoppen und Container entfernen (Volumes bleiben erhalten) |
docker compose ps | Status der Container im Stack anzeigen |
docker compose logs -f | Logs live mitverfolgen |
docker compose pull | Aktuelle Images herunterladen |
docker compose up -d --build | Images neu bauen und Stack aktualisieren |
docker compose restart | Dienste neu starten |
Häufige Fehler vermeiden
- Falsche Einrückung in der YAML: YAML ist einrückungssensitiv. Verwende ausschließlich Leerzeichen (keine Tabs) und halte die Struktur sauber ein.
- Portkonflikte: Ist der Host-Port bereits belegt, startet der Container nicht. Wähle einen freien Port oder gib den blockierenden Dienst frei.
- Rechteprobleme bei Volumes: Achte auf die Besitzrechte der gemounteten Verzeichnisse. Eine Übersicht typischer Stolperfallen findest du in Die 10 häufigsten Docker-Fehler.
Fazit
Mit dem offiziellen APT-Repository ist Docker Compose unter Ubuntu und Debian in wenigen Minuten installiert – inklusive Engine und automatischer Updates. Du nutzt die gepflegte Version 2 (docker compose), definierst deine Dienste in einer übersichtlichen YAML-Datei und startest komplette Setups mit einem einzigen Befehl. Logische nächste Schritte: deine Daten mit Docker Volumes sichern, die Container-Vernetzung verstehen, deine Container automatisch aktuell halten oder sie mit dem Nginx Proxy Manager sicher aus dem Internet erreichbar machen. Feinschliff holst du dir mit Umgebungsvariablen & .env und Restart-Policies.
