Docker Compose Anleitung für Einsteiger: Datei und Befehle

Die Docker-Doku von FreshRSS zeigt zum Einstieg einen einzigen Befehl. Er geht über acht Zeilen, jede endet mit einem Backslash, und dazwischen stehen ein Port, eine Zeitzone, ein Zeitplan, zwei Speicherorte, ein Name und ein Image. Wer ihn abtippt, bekommt einen laufenden Feed-Reader. Wer ihn eine Woche später ändern will, sucht erst mal in der Shell-History, wie er damals genau lautete.

Docker Compose ist die Antwort auf dieses Suchen. Derselbe Befehl wird eine Datei, die im Ordner liegt, die man lesen und ändern kann, und die mit einem einzigen docker compose up -d zum laufenden Dienst wird. Fast jede Anleitung auf dieser Seite endet in so einer Datei. Diese hier erklärt sie einmal von vorn: Zeile für Zeile, an einem Dienst, der klein genug ist, dass die Datei nicht ablenkt.

Was Docker Compose ist

Docker packt ein Programm samt allem, was es zum Laufen braucht, in ein Image: ein fertiges Paket, das jemand anders gebaut und auf einen öffentlichen Server gelegt hat, den Docker Hub. Aus dem Image macht Docker auf deinem Rechner einen Container, das laufende Programm in seinem eigenen kleinen Zimmer, mit eigener Netzwerkadresse und eigenem Dateisystem. Das Image ist die Backmischung, der Container der Kuchen.

Damit der Kuchen brauchbar wird, muss Docker ein paar Dinge wissen: Über welchen Port darfst du von außen an das Zimmer klopfen? Wo sollen die Daten hin, die den Container überleben sollen? Welche Zeitzone gilt drinnen? Und was passiert, wenn der Rechner neu startet? Beim docker run-Befehl stehen die Antworten als Optionen hintereinander. Bei Compose stehen sie in einer Datei, und der Befehl bleibt immer derselbe.

Die Datei heißt compose.yaml. Die Docker-Doku nennt diesen Namen ausdrücklich den bevorzugten; docker-compose.yml aus älteren Anleitungen versteht Compose weiterhin, und liegen beide im Ordner, gewinnt compose.yaml. Ich nehme den neuen Namen, weil er die Tutorials von 2019 sauber von den heutigen trennt. In denselben alten Tutorials steht ganz oben eine Zeile version: "3". Die ist laut Doku überholt und wird nur noch mit einer Warnung quittiert. Weglassen.

Compose ist seit Version 2 ein Teil von Docker selbst und wird als docker compose mit Leerzeichen aufgerufen. Das ältere docker-compose mit Bindestrich war ein eigenes Programm, das nicht mehr gepflegt wird. Meldet dein Rechner nur den Bindestrich, ist das die alte Version 1, und dann lohnt der Weg über Schritt 1 unten, weil das offizielle Installationsskript die aktuelle mitbringt.

Was du brauchst

• Einen Rechner mit Debian oder Ubuntu, auf dem du ein Terminal öffnen kannst. Das kann ein alter Büro-PC sein, ein Raspberry Pi oder eine VM. Docker gibt es für amd64 und arm64; das FreshRSS-Image ebenso, plus arm/v7 für ältere Pis.
• Ein Konto auf diesem Rechner, das sudo darf, also Befehle mit Verwaltungsrechten ausführen. Beim ersten Benutzer einer Debian- oder Ubuntu-Installation ist das meist der Fall.
• Port 8080 frei. Prüfen wir gleich.
• Einen Browser auf einem Gerät im selben Netz, und sei es derselbe Rechner.

Alle Befehle rechnen mit denselben Beispielwerten. Wo sie unten auftauchen, setzt du deine ein:

Schritt 1: Docker prüfen oder installieren

Zuerst die Frage, ob Docker schon da ist. Öffne ein Terminal auf dem Rechner, das schwarze Fenster, in das man Befehle tippt; steht der Rechner ohne Bildschirm im Keller, verbindest du dich von deinem PC aus per SSH, das ist ein Terminal über das Netzwerk. Dann:

docker --version
docker compose version

Docker version 29.8.1, build 4a63305
Docker Compose version v5.5.1

Stehen da zwei Versionsnummern, springst du zu Schritt 2. Steht da docker: command not found, fehlt Docker, und du installierst es mit dem Skript, das Docker selbst für diesen Zweck anbietet. Das Skript erkennt deine Distribution, richtet die Paketquelle von Docker ein und installiert Docker samt Compose-Plugin. Die Doku warnt, dass es nur für frische Installationen gedacht ist und keine bestehende aktualisiert; genau das ist hier der Fall.

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

sudo usermod -aG docker $USER

docker run hello-world

Hello from Docker!
This message shows that your installation appears to be working correctly.

Ein Satz zur Gruppe docker, weil die Doku ihn auch sagt: Wer in dieser Gruppe ist, kann über Docker alles auf dem Rechner tun, was Root kann. Für deinen eigenen Rechner zu Hause ist das in Ordnung; auf einem Server, den sich mehrere Leute teilen, würde ich es mir überlegen.

Bleibt der Port. FreshRSS bekommt gleich Port 8080, und der ist auf Bastelrechnern beliebt. Der Befehl darf nichts außer der Meldung ausgeben:

sudo ss -tulpn | grep ':8080 ' || echo "Port 8080 ist frei"

Port 8080 ist frei

Kommt stattdessen eine Zeile mit einem Programmnamen, sitzt dort schon jemand. Wer das ist und wie du ihn wegbekommst, steht in einem eigenen Beitrag; oder du gibst FreshRSS in Schritt 2 einen anderen Port, das ist eine Zahl in der Datei.

Schritt 2: Die Compose-Datei

Jeder Compose-Dienst bekommt einen eigenen Ordner. Der Name des Ordners ist nicht Deko: Compose nennt das Ganze ein Projekt und leitet den Projektnamen aus dem Ordnernamen ab, und mit dem Projektnamen werden gleich die Speicherbereiche benannt. Zwei Dienste im selben Ordner kämen sich in die Quere.

mkdir -p ~/freshrss
cd ~/freshrss

nano compose.yaml

services:
  freshrss:
    image: freshrss/freshrss:latest
    container_name: freshrss
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - data:/var/www/FreshRSS/data
      - extensions:/var/www/FreshRSS/extensions
    environment:
      TZ: Europe/Berlin
      CRON_MIN: '2,32'

volumes:
  data:
  extensions:

docker compose config --quiet && echo "Datei in Ordnung"

Datei in Ordnung

Die Datei ist die aus der Docker-Doku von FreshRSS, um zwei Zeilen erleichtert, die nur für Entwickler gedacht sind, und mit deutscher Zeitzone. Sie ist im Sandkasten dieser Seite gelaufen, bevor sie hier steht. Jetzt das Wichtigste dieser Anleitung: was jede Zeile tut.

Ein Wort zu den Volumes, weil sie Einsteiger am meisten verwirren. Es gibt zwei Arten, einem Container einen dauerhaften Speicherort zu geben. Die eine ist ein Bind Mount: Du nennst einen Ordner auf deinem Rechner, etwa ./data:/var/www/FreshRSS/data, und der Container schreibt direkt hinein; du siehst die Dateien im Dateimanager. Die andere ist das benannte Volume wie hier: Docker legt den Ordner selbst an, unter /var/lib/docker/volumes/, und kümmert sich um die Rechte. FreshRSS nutzt in seinen Docker-Beispielen durchgehend die zweite Form, und für den ersten Dienst ist sie die entspanntere, weil die Frage „welcher Benutzer darf in diesen Ordner schreiben" gar nicht erst aufkommt. Der Preis ist, dass du für ein Backup einmal mehr nachsehen musst, wo die Daten liegen. Das machen wir am Ende.

Schritt 3: Starten und zusehen

Der eine Befehl. Er lädt das Image herunter, legt die Volumes an, baut den Container und startet ihn; -d steht für detached, im Hintergrund, damit du das Terminal zurückbekommst.

docker compose up -d

[+] Running 4/4
 ✔ Network freshrss_default       Created
 ✔ Volume "freshrss_data"         Created
 ✔ Volume "freshrss_extensions"   Created
 ✔ Container freshrss             Started

Vier Häkchen, und in den Namen steckt der Projektname aus dem Ordner: freshrss_data, nicht data. Ein eigenes Netz hat Compose auch angelegt, ohne dass es in der Datei stand; das bekommt jedes Projekt, und mehrere Container im selben Projekt reden darüber miteinander. Dann die Frage, ob der Container auch läuft und nicht nur gestartet wurde:

docker compose ps

NAME       IMAGE                      COMMAND                  SERVICE    CREATED                  STATUS                  PORTS
freshrss   freshrss/freshrss:latest   "./Docker/entrypoint…"   freshrss   Less than a second ago   Up Less than a second   0.0.0.0:8080->80/tcp, [::]:8080->80/tcp

Die Spalte STATUS ist die, die zählt. Up mit einer Zeit heißt: läuft. Stünde dort Restarting, würde der Container in einer Schleife abstürzen und neu starten, und dann will man wissen, warum. Dafür gibt es die Logs, das ist alles, was das Programm im Container auf seine Konsole schreibt:

docker compose logs --tail 20

Die letzten zwanzig Zeilen; bei FreshRSS sind es Apache-Meldungen, die nichts Schlimmes sagen sollten. Mit -f statt --tail 20 bleibt die Ausgabe offen und zeigt neue Zeilen, sobald sie kommen, bis du mit Strg+C aussteigst. Das ist der Befehl, den du bei jedem künftigen Problem als Erstes tippst, egal bei welchem Container.

Schritt 4: FreshRSS im Browser einrichten

Der Container läuft, aber FreshRSS weiß noch nicht, wem er gehört. Das klärt ein Assistent in fünf Seiten.

SQLite ist eine Datenbank, die aus einer einzigen Datei besteht und ohne eigenen Server auskommt; sie liegt im Volume data. Für einen Haushalt, der Nachrichten liest, reicht sie vollkommen. Der Benutzer, den du gerade angelegt hast, ist der Administrator dieser Installation; weitere Benutzer legt er später unter Administration an.

Der Beweis, dass alles zusammenspielt, ist ein erster Feed. Der von dieser Seite bietet sich an, aber jeder andere tut es auch:

Erscheinen die letzten Beiträge in der Liste, hast du gerade den ganzen Weg gesehen: Browser, Port 8080, Container, Volume. Und FreshRSS holt die Feeds ab jetzt zweimal die Stunde von selbst, zu den Minuten 2 und 32, weil das in CRON_MIN steht.

Die fünf Befehle, die du behältst

Alles, was du bis hier getippt hast, gilt für jeden Compose-Dienst, nicht nur für FreshRSS. Immer im Ordner mit der compose.yaml, also nach einem cd ~/freshrss:

docker compose up -d

docker compose ps

docker compose logs -f

docker compose down

docker compose pull
docker compose up -d

Zu down gehört eine Warnung, und sie ist der Grund, warum ich das Wort Volume oben so lange erklärt habe. docker compose down lässt die Volumes in Ruhe, das steht so in der Doku. docker compose down -v löscht sie mit, und damit Datenbank, Konten und Feeds. Der Buchstabe ist der Unterschied zwischen „kurz aus" und „alles weg". Man tippt ihn genau einmal versehentlich. Ich erwähne das Backup deshalb jetzt schon und nicht erst am Ende.

Was am Ende eingestellt ist

1. Ein Konto, und das ist der Admin. Anmeldung per Webformular, Passwort in der SQLite-Datei im Volume. Wer FreshRSS mit der Familie teilt, legt unter Administration weitere Benutzer an, statt das eine Passwort herumzugeben.
2. Port 8080 ist im ganzen Heimnetz offen. In docker compose ps steht 0.0.0.0:8080, und das heißt: auf allen Adressen des Rechners. Jeder im WLAN sieht die Anmeldeseite. Aus dem Internet sieht sie niemand, solange du im Router keinen Port freigibst, und das würde ich für einen Dienst ohne HTTPS auch nicht tun. Wenn irgendwann ein Reverse Proxy davor steht, änderst du die Zeile in "127.0.0.1:8080:80"; dann nimmt nur noch der Proxy auf demselben Rechner ab. Auch das ist eine Zeile in der Datei und ein up -d.
3. Feeds laden alle 30 Minuten. Wer es häufiger will, trägt bei CRON_MIN mehr Minuten ein, etwa '2,17,32,47'. Häufiger als alle 15 Minuten ist gegenüber den Seiten, die du liest, unhöflich und bringt nichts; die meisten Blogs schreiben nicht viermal die Stunde.
4. Updates macht niemand für dich. Mit dem Tag latest bekommst du bei jedem pull die neueste stabile Version, aber den pull tippst du selbst. Einmal im Monat ist ein guter Rhythmus, und vorher einen Blick in die Release Notes; FreshRSS schreibt dort, wenn etwas bricht. Bei 1.30.0 stand so etwas drin, dazu gleich mehr.
5. Das Backup liegt in Dockers Ordner. Wo genau, verrät docker volume inspect freshrss_data in der Zeile Mountpoint, und weil der Ordner Root gehört, brauchst du sudo, um ihn zu kopieren. Stoppe den Container vorher mit down, damit die Datenbank nicht mitten im Schreiben kopiert wird. Wie das für alle Volumes auf einmal und regelmäßig geht, ist ein eigener Beitrag; der ist vorgemerkt.
6. Die Logs wachsen ungebremst. Docker hebt alles auf, was der Container auf die Konsole schreibt, und begrenzt das nicht von selbst. Die offizielle FreshRSS-Datei hat dafür einen Block logging: mit max-size: 10m; wer den Dienst monatelang laufen lässt, nimmt ihn dazu. Für die ersten Wochen ist es egal.

Wo es klemmt

Warnung wegen version. Steht in einer kopierten Datei die Zeile version: "3", meldet Compose beim Start, das Attribut sei überholt und werde ignoriert. Es ist eine Warnung, kein Fehler, aber die Zeile ist ein Zeichen, dass das Tutorial älter ist als der Rest deiner Installation. Löschen.

Fehler mit Zeilennummer beim config oder up. Fast immer die Einrückung. YAML zählt Leerzeichen, ein Tabulator gilt nicht, und ports: muss genau zwei Leerzeichen tiefer stehen als freshrss:. Vergleiche die genannte Zeile mit der Datei oben; das Lesen der Fehlermeldung übernimmt docker compose config, das die Datei nur prüft, ohne etwas zu starten.

Bind for 0.0.0.0:8080 failed: port is already allocated. Ein anderer Container oder ein anderes Programm hat den Port. Entweder den Port in der Datei ändern, oder herausfinden, wer ihn hält.

permission denied while trying to connect to the Docker daemon socket. Dein Konto ist noch nicht in der Gruppe docker, oder du hast dich nach dem usermod nicht neu angemeldet. Abmelden, anmelden, noch mal. Solange gehen die Befehle auch mit sudo davor.

docker-compose: command not found. Die Anleitung, aus der der Befehl stammt, meint die alte Version 1. Bindestrich durch Leerzeichen ersetzen, der Rest des Befehls bleibt gleich.

FreshRSS nimmt einen Feed aus dem Heimnetz nicht an. Seit 1.30.0 blockiert FreshRSS Adressen aus lokalen Netzen standardmäßig; die Standardkonfiguration nennt 127.0.0.1 und die privaten Bereiche 10.0.0.0/8, 172.16.0.0/12 und 192.168.0.0/16, also auch dein Heimnetz. Das Changelog nennt es als absichtlichen Bruch, um sogenannte SSRF-Angriffe zu erschweren, bei denen ein Angreifer den Reader als Sprungbrett ins interne Netz nutzt. Wer einen Feed von seinem eigenen Server abonnieren will, etwa von einer Gitea-Instanz, trägt dessen Adresse laut Changelog in der Systemkonfiguration oder über die Umgebungsvariable INTERNAL_HOST_ALLOWLIST ein. Dass ein Projekt dieser Größe so einen Bruch in Kauf nimmt und ihn in den Release Notes als Erstes nennt, ist das Verhalten, das ich mir von Software wünsche.

Die Datei ist jetzt keine Zauberformel mehr. Wenn du das nächste Mal eine compose.yaml auf dieser Seite siehst, bei n8n oder Jellyfin, wirst du jede Zeile einer der neun aus der Tabelle zuordnen können, und die zwei oder drei neuen erklärt der jeweilige Beitrag. Welcher Dienst ist bei dir der erste, der in einen Ordner mit einer compose.yaml zieht, und welche Zeile war die, an der es gehakt hat? Ab damit in die Kommentare.

Wenn dir eine solche Erklärung von vorn öfter fehlt, bei DNS, beim Reverse Proxy, bei Containern gegen VMs, dann ist der Newsletter der Ort, an dem du diese Grundlagen-Beiträge nicht verpasst.

Quellen

• Docker Docs: The Compose application model (Dateinamen, Dienste, Volumes, Netze)
• Docker Docs: Compose file reference, Services (image, ports, volumes, environment, restart)
• Docker Docs: Compose file reference, version und name
• Docker Docs: docker compose CLI (Projektname, Unterbefehle)
• Docker Docs: docker compose up
• Docker Docs: docker compose down
• Docker Docs: Install Docker Engine on Debian (Installationsskript)
• Docker Docs: Linux post-installation steps (Gruppe docker)
• FreshRSS: Docker README (docker run, Compose-Beispiel, Umgebungsvariablen, Tags)
• FreshRSS 1.30.0: Release Notes
• FreshRSS: Changelog (SSRF-Schutz, INTERNAL_HOST_ALLOWLIST)
• FreshRSS: config.default.php (blockierte Adressbereiche)
• FreshRSS: install.php (Schritte und Felder des Einrichtungsassistenten)