Admin: /* Kritik in der Fachwelt */

2026-04-24T12:20:59Z

Kritik in der Fachwelt

← Nächstältere Version		Version vom 24. April 2026, 12:20 Uhr
Zeile 67:		Zeile 67:
	<code>NO</code> wird in älteren YAML-Parsern automatisch zu <code>false</code>		<code>NO</code> wird in älteren YAML-Parsern automatisch zu <code>false</code>
	— was dazu geführt hat dass norwegische Entwickler in Konfigurationsdateien		— was dazu geführt hat dass norwegische Entwickler in Konfigurationsdateien
	ihren eigenen Ländercode nicht als String verwenden konnten ohne Anführungszeichen.		ihren eigenen Ländercode nicht als String verwenden konnten ohne Anführungszeichen.🤣

	YAML 1.2 (2009) hat viele dieser Probleme behoben, aber ältere Parser sind		YAML 1.2 (2009) hat viele dieser Probleme behoben, aber ältere Parser sind

Admin am 24. April 2026 um 12:06 Uhr

2026-04-24T12:06:40Z

Änderungen zeigen

Admin: Die Seite wurde neu angelegt: „== docker-compose.yml — Referenz und Konzepte == Dieser Artikel erklärt den Aufbau und die Direktiven einer `docker-compose.yml` auf Deutsch. Er richtet sich an alle die Docker Compose produktiv einsetzen und eine kompakte Nachschlageseite in ihrer eigenen Sprache brauchen. Die offizielle Referenz ist ausschließlich auf Englisch verfügbar: [https://docs.docker.com/compose/compose-file/ docs.docker.com/compose/compose-file] ---- == YAML…“

2026-04-24T11:57:00Z

Die Seite wurde neu angelegt: „== docker-compose.yml — Referenz und Konzepte == Dieser Artikel erklärt den Aufbau und die Direktiven einer <code>docker-compose.yml</code> auf Deutsch. Er richtet sich an alle die Docker Compose produktiv einsetzen und eine kompakte Nachschlageseite in ihrer eigenen Sprache brauchen. Die offizielle Referenz ist ausschließlich auf Englisch verfügbar: [https://docs.docker.com/compose/compose-file/ docs.docker.com/compose/compose-file] ---- == YAML…“

Neue Seite

== docker-compose.yml — Referenz und Konzepte ==

Dieser Artikel erklärt den Aufbau und die Direktiven einer <code>docker-compose.yml</code>
auf Deutsch. Er richtet sich an alle die Docker Compose produktiv einsetzen und eine
kompakte Nachschlageseite in ihrer eigenen Sprache brauchen.

Die offizielle Referenz ist ausschließlich auf Englisch verfügbar:
[https://docs.docker.com/compose/compose-file/ docs.docker.com/compose/compose-file]

----

== YAML — die Auszeichnungssprache ==

YAML steht für „YAML Ain't Markup Language" — ein rekursives Akronym, typisch für
die Open-Source-Welt. Es ist eine Sprache zur Darstellung strukturierter Daten,
die für Menschen lesbar sein soll.

=== YAML und JSON — Verwandtschaft, kein Dialekt ===

JSON und YAML sind '''verwandt, aber nicht dasselbe'''. Der häufige Vergleich
„YAML ist ein JSON-Dialekt" ist ungenau:

* Jedes gültige JSON ist auch gültiges YAML — YAML ist eine Obermenge von JSON.
* Umgekehrt gilt das nicht: YAML kann Dinge ausdrücken die JSON nicht kann
(Kommentare, mehrzeilige Strings, Anker und Referenzen).
* Die Syntax ist völlig unterschiedlich: JSON verwendet geschweifte Klammern
und Anführungszeichen, YAML verwendet Einrückung und Doppelpunkte.

Dasselbe Datenkonstrukt in beiden Sprachen:

<syntaxhighlight lang="json">
{
"services": {
"nextcloud": {
"image": "nextcloud:latest",
"restart": "unless-stopped"
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="yaml">
services:
nextcloud:
image: nextcloud:latest
restart: unless-stopped
</syntaxhighlight>

YAML ist lesbarer — auf Kosten einer strengen Einrückungsregel: '''Einrückung
mit Leerzeichen, niemals mit Tabs.''' Ein falsch gesetzter Tab ist der häufigste
Fehler in compose-Dateien.

=== Kommentare ===

YAML unterstützt Kommentare mit <code>#</code> — JSON nicht.
Das macht YAML deutlich besser geeignet für Konfigurationsdateien die Menschen
pflegen:

<syntaxhighlight lang="yaml">
# Dieser Container darf keinen direkten Außenzugriff haben
ports: [] # keine ports → kein direkter Zugriff von außen
</syntaxhighlight>

=== Datentypen ===

YAML erkennt Datentypen automatisch:

{| class="wikitable"
! Wert !! Typ !! Anmerkung
|-
| <code>true</code> / <code>false</code> || Boolean || Ohne Anführungszeichen
|-
| <code>42</code> || Integer ||
|-
| <code>3.14</code> || Float ||
|-
| <code>hallo</code> || String || Ohne Anführungszeichen wenn eindeutig
|-
| <code>"true"</code> || String || Mit Anführungszeichen erzwungen
|-
| <code>null</code> || Null ||
|}

Stolperfalle: <code>restart: always</code> ist ein String. <code>restart: true</code>
wäre ein Boolean — und ungültig. Im Zweifel Anführungszeichen setzen.

----

== Grundaufbau einer docker-compose.yml ==

Eine <code>docker-compose.yml</code> besteht aus maximal vier Abschnitten
auf oberster Ebene:

<syntaxhighlight lang="yaml">
services: # Pflicht — definiert die Container
...

networks: # Optional — definiert Netzwerke
...

volumes: # Optional — definiert persistente Datenspeicher
...

configs: # Optional — definiert Konfigurationsdateien
...
</syntaxhighlight>

Der <code>services</code>-Abschnitt ist der einzig verpflichtende.
Alles andere ist optional und wird nur angegeben wenn benötigt.

=== Einrückungsregeln ===

Die Hierarchie wird ausschließlich durch Einrückung ausgedrückt.
Zwei Leerzeichen pro Ebene sind Konvention:

<syntaxhighlight lang="yaml">
services: # Ebene 1
nextcloud: # Ebene 2 — Name des Dienstes
image: ... # Ebene 3 — Direktive des Dienstes
networks: # Ebene 3 — Direktive (Liste folgt)
- tuxi_net # Ebene 4 — Listenelement
</syntaxhighlight>

----

== Direktiven im services-Abschnitt ==

=== image ===

Das Docker-Image das für den Container verwendet wird.

<syntaxhighlight lang="yaml">
services:
nextcloud:
image: lscr.io/linuxserver/nextcloud:latest
</syntaxhighlight>

Format: <code>registry/image:tag</code>. Ohne Registry wird Docker Hub angenommen.
Ohne Tag wird <code>latest</code> angenommen — aber explizit angeben ist besser
für Reproduzierbarkeit.

=== container_name ===

Fester Name des Containers. Ohne diese Direktive generiert Docker Compose
einen Namen aus Projektname + Servicename + Nummer.

<syntaxhighlight lang="yaml">
services:
nextcloud:
container_name: nextcloud
</syntaxhighlight>

Wichtig: der Container-Name ist gleichzeitig der Docker-interne DNS-Name
mit dem andere Container diesen Dienst ansprechen können.

=== restart ===

Neustart-Verhalten des Containers.

<syntaxhighlight lang="yaml">
restart: unless-stopped
</syntaxhighlight>

{| class="wikitable"
! Wert !! Verhalten
|-
| <code>no</code> || Nie neu starten (Standard)
|-
| <code>always</code> || Immer neu starten, auch nach manuellem Stopp
|-
| <code>unless-stopped</code> || Neu starten außer wenn manuell gestoppt — empfohlen für Produktionsdienste
|-
| <code>on-failure</code> || Nur neu starten wenn der Container mit Fehlercode endet
|}

=== image vs. build ===

Statt ein fertiges Image zu verwenden kann Docker Compose auch selbst eines bauen:

<syntaxhighlight lang="yaml">
services:
mein-dienst:
build:
context: ./mein-verzeichnis # Pfad zum Dockerfile
dockerfile: Dockerfile.prod # optional: anderer Dateiname
</syntaxhighlight>

=== ports ===

Portweiterleitung zwischen Host und Container: <code>HOST:CONTAINER</code>.

<syntaxhighlight lang="yaml">
services:
caddy:
ports:
- "80:80"
- "443:443"
- "443:443/udp" # für HTTP/3
</syntaxhighlight>

'''Wichtig:''' Wer <code>ports</code> weglässt, ist nur im Docker-Netzwerk erreichbar —
nicht von außen. Das ist für interne Dienste wie Datenbanken oder Collabora gewünscht.

=== volumes ===

Einbinden von Verzeichnissen oder benannten Volumes in den Container.

<syntaxhighlight lang="yaml">
services:
nextcloud:
volumes:
- ./nextcloud/app:/config # Bind Mount: Host-Pfad → Container-Pfad
- /data/nextcloud-data:/data # absoluter Host-Pfad
- caddy_data:/data # benanntes Volume (unten definiert)

volumes:
caddy_data: # benanntes Volume — Docker verwaltet den Speicherort
</syntaxhighlight>

{| class="wikitable"
! Typ !! Syntax !! Wann verwenden
|-
| Bind Mount || <code>./host/pfad:/container/pfad</code> || Wenn du direkten Zugriff auf die Dateien brauchst
|-
| Benanntes Volume || <code>volume_name:/container/pfad</code> || Für Datenbankdaten, Caches — Docker verwaltet den Speicherort
|-
| tmpfs || Siehe <code>tmpfs</code>-Direktive || Flüchtige Daten die nur im RAM leben sollen
|}

=== environment ===

Umgebungsvariablen die in den Container übergeben werden.

<syntaxhighlight lang="yaml">
services:
nextcloud:
environment:
- PUID=1000
- PGID=1001
- TZ=Europe/Berlin
- MYSQL_PASSWORD=${MYSQL_PASSWORD} # Wert aus .env-Datei
</syntaxhighlight>

Alternativ als Map-Schreibweise:

<syntaxhighlight lang="yaml">
environment:
PUID: "1000"
TZ: Europe/Berlin
</syntaxhighlight>

=== env_file ===

Umgebungsvariablen aus einer externen Datei laden statt sie in der compose-Datei
zu hartcodieren — sinnvoll für Passwörter und Secrets:

<syntaxhighlight lang="yaml">
services:
nc-db:
env_file:
- .env
</syntaxhighlight>

Die <code>.env</code>-Datei enthält dann:

<syntaxhighlight lang="bash">
MYSQL_ROOT_PASSWORD=sehrgeheim
MYSQL_DATABASE=nextcloud
MYSQL_USER=ncuser
MYSQL_PASSWORD=auchhgeheim
</syntaxhighlight>

Die <code>.env</code>-Datei gehört in <code>.gitignore</code> — niemals in ein
öffentliches Repository einchecken.

=== networks ===

Netzwerkzugehörigkeit des Containers.

<syntaxhighlight lang="yaml">
services:
nextcloud:
networks:
tuxi_network:
ipv4_address: 172.18.0.20 # feste IP (optional)

collabora:
networks: [tuxi_network] # Kurzschreibweise ohne feste IP

networks:
tuxi_network:
external: true # Netzwerk existiert bereits, nicht neu anlegen
</syntaxhighlight>

Ohne <code>networks</code>-Angabe landet der Container im automatisch erstellten
Default-Netzwerk des Projekts — Container in verschiedenen Projekten können sich
dann nicht erreichen.

=== extra_hosts ===

Einträge die direkt in die <code>/etc/hosts</code> des Containers geschrieben werden.
Überschreibt DNS — wird vor jeder DNS-Anfrage ausgewertet.

<syntaxhighlight lang="yaml">
services:
nextcloud:
extra_hosts:
- "collabora.beispiel.de:172.18.0.6"
</syntaxhighlight>

Typischer Anwendungsfall: Hairpinning vermeiden — ein Container soll eine Domain
intern auflösen statt den Umweg über die externe IP zu nehmen.
Siehe [[Hairpin-NAT – Collabora und Nextcloud hinter Caddy]].

=== depends_on ===

Startreihenfolge und Abhängigkeiten zwischen Diensten.

<syntaxhighlight lang="yaml">
services:
nextcloud:
depends_on:
db:
condition: service_healthy # wartet bis Healthcheck grün ist
redis:
condition: service_healthy
</syntaxhighlight>

{| class="wikitable"
! condition !! Bedeutung
|-
| <code>service_started</code> || Container wurde gestartet (Standard — prüft nicht ob er wirklich läuft)
|-
| <code>service_healthy</code> || Healthcheck des abhängigen Dienstes ist grün
|-
| <code>service_completed_successfully</code> || Abhängiger Dienst hat sich mit Exit-Code 0 beendet
|}

=== healthcheck ===

Prüft ob der Container wirklich funktioniert — nicht nur ob er läuft.

<syntaxhighlight lang="yaml">
services:
nc-db:
healthcheck:
test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -u root -p$$MYSQL_ROOT_PASSWORD || exit 1"]
interval: 10s # wie oft prüfen
timeout: 5s # wie lange auf Antwort warten
retries: 30 # wie oft wiederholen bevor unhealthy
start_period: 30s # Anlaufzeit bevor Healthcheck zählt
</syntaxhighlight>

Das <code>$$</code> ist kein Tippfehler — doppeltes Dollar-Zeichen verhindert
dass Compose die Variable selbst auflöst; sie wird stattdessen an die Shell
im Container übergeben.

=== tmpfs ===

Flüchtige Dateisysteme die nur im RAM leben und beim Container-Stopp verschwinden.
Für temporäre Daten, Caches und Security-Härtung:

<syntaxhighlight lang="yaml">
services:
nc-redis:
tmpfs:
- /data
- /tmp
- /run

collabora:
tmpfs:
- /tmp
- /var/tmp
</syntaxhighlight>

Redis im RAM-only-Modus: schneller, kein Disk-I/O, Daten gehen beim Neustart verloren —
für Session-Caches gewünscht.

=== dns ===

DNS-Server die der Container verwenden soll statt des Docker-Defaults.

<syntaxhighlight lang="yaml">
services:
nextcloud:
dns:
- 1.1.1.1 # Cloudflare
- 9.9.9.9 # Quad9
- 8.8.8.8 # Google
</syntaxhighlight>

=== command ===

Überschreibt den Standard-Startbefehl des Images.

<syntaxhighlight lang="yaml">
services:
nc-db:
command: --transaction-isolation=READ-COMMITTED --binlog-format=ROW
</syntaxhighlight>

=== security_opt und cap_drop / cap_add ===

Container-Härtung: Linux-Capabilities entziehen oder hinzufügen.

<syntaxhighlight lang="yaml">
services:
nc-redis:
security_opt:
- no-new-privileges:true # verhindert Privilege Escalation
cap_drop:
- ALL # alle Capabilities entziehen
cap_add:
- NET_BIND_SERVICE # nur diese eine wieder erlauben (z.B. für Ports <1024)
</syntaxhighlight>

Faustregel aus dem Kommentarteil deiner compose-Datei:
* <code>no-new-privileges: true</code> — immer möglich, immer gut
* <code>cap_drop: ALL</code> — wo immer es geht
* <code>read_only: true</code> — nur bei schlanken Services ohne viele Schreibpfade

=== read_only ===

Container-Dateisystem schreibgeschützt — kombiniert mit <code>tmpfs</code> für
Verzeichnisse die Schreibzugriff benötigen:

<syntaxhighlight lang="yaml">
services:
nc-redis:
read_only: true
tmpfs:
- /data
- /tmp
- /run
</syntaxhighlight>

----

== Der networks-Abschnitt ==

=== Externes Netzwerk verwenden ===

<syntaxhighlight lang="yaml">
networks:
tuxi_network:
external: true # Netzwerk wurde bereits mit docker network create angelegt
</syntaxhighlight>

=== Neues Netzwerk anlegen ===

<syntaxhighlight lang="yaml">
networks:
mein_netzwerk:
driver: bridge
ipam:
config:
- subnet: 172.20.0.0/16
gateway: 172.20.0.1
</syntaxhighlight>

----

== Der volumes-Abschnitt ==

=== Benanntes Volume ===

<syntaxhighlight lang="yaml">
volumes:
caddy_data: # Docker verwaltet den Speicherort unter /var/lib/docker/volumes/
caddy_config:
</syntaxhighlight>

=== Volume mit tmpfs-Treiber (RAM-Disk) ===

<syntaxhighlight lang="yaml">
volumes:
cool-child-roots:
driver_opts:
type: tmpfs
device: tmpfs
o: "size=4g,mode=1777"
</syntaxhighlight>

----

== Nützliche CLI-Befehle ==

{| class="wikitable"
! Befehl !! Was er tut
|-
| <code>docker compose up -d</code> || Alle Dienste im Hintergrund starten
|-
| <code>docker compose down</code> || Alle Dienste stoppen und Container entfernen
|-
| <code>docker compose restart</code> || Alle Dienste neu starten
|-
| <code>docker compose restart caddy</code> || Nur einen Dienst neu starten
|-
| <code>docker compose up -d --force-recreate nextcloud</code> || Einen Container neu erstellen (bei Konfigurationsänderungen)
|-
| <code>docker compose logs -f nextcloud</code> || Log eines Dienstes live verfolgen
|-
| <code>docker compose ps</code> || Status aller Dienste anzeigen
|-
| <code>docker compose exec nextcloud bash</code> || Shell in laufendem Container öffnen
|-
| <code>docker compose pull</code> || Alle Images aktualisieren
|}

----

== Häufige Fehler ==

{| class="wikitable"
! Fehler !! Ursache !! Fix
|-
| <code>yaml: line X: found character that cannot start any token</code> || Tab statt Leerzeichen zur Einrückung || Alle Tabs durch Leerzeichen ersetzen
|-
| <code>Address already in use</code> || Feste IP bereits von anderem Container belegt || <code>docker network inspect</code> → Schuldigen finden
|-
| Container startet, aber Dienst funktioniert nicht || <code>depends_on</code> ohne <code>condition: service_healthy</code> || Healthcheck ergänzen und <code>service_healthy</code> verwenden
|-
| Umgebungsvariable leer obwohl in <code>.env</code> gesetzt || <code>.env</code> liegt nicht im selben Verzeichnis wie die compose-Datei || Pfad prüfen oder <code>env_file</code> explizit angeben
|-
| <code>$$VARIABLE</code> wird nicht aufgelöst || Gewolltes Verhalten — <code>$$</code> wird zu <code>$</code> und an die Shell übergeben || Für Shell-Variablen im Container: <code>$$</code> verwenden. Für Compose-Variablen: <code>$</code>
|}

----

== Siehe auch ==

* [[Webserver, Reverse Proxy und Container – wie die Schichten zusammenspielen]]
* [[Docker-Netzwerke und Container-IPs — Konfiguration und Fallstricke]]
* [[Hairpin-NAT – Collabora und Nextcloud hinter Caddy]]
* [https://docs.docker.com/compose/compose-file/ Offizielle Compose-Referenz (englisch)]

[[Kategorie:Docker]]

YAML: Die Auszeichnungssprache in der Docker-Compose-Welt - Versionsgeschichte

Admin: /* Kritik in der Fachwelt */

Admin am 24. April 2026 um 12:06 Uhr