Quelltext der Seite YAML: Die Auszeichnungssprache in der Docker-Compose-Welt

== YAML — Die Auszeichnungssprache in der Docker-Compose-Welt ==

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.

----

== Geschichte ==

YAML wurde 2001 von drei Entwicklern entworfen: Clark Evans, Ingy döt Net
und Oren Ben-Kiki. Das ursprüngliche Akronym lautete noch „Yet Another Markup
Language" — in Anlehnung an die vielen XML-Varianten der Zeit. Es wurde bald
zu „YAML Ain't Markup Language" umgedeutet, um klarzustellen: das hier ist
keine Dokumentensprache wie HTML oder XML, sondern eine reine Datensprache.

Das Grundproblem das YAML lösen wollte war real: XML war für Konfigurationsdateien
viel zu geschwätzig — jeder Wert brauchte ein öffnendes und schließendes Tag.
JSON existierte noch gar nicht (das kam erst 2002). Man wollte etwas das Menschen
wirklich lesen und schreiben können, ohne ständig spitze Klammern tippen zu müssen.

=== Verbreitung vor Docker ===

Docker hat YAML nicht erfunden — es hat YAML einer neuen Generation bekannt gemacht.
Vorher war YAML in anderen Welten zuhause:

* '''Ruby on Rails''' (2004) — der erste große Durchbruch. Rails verwendete YAML
  für Datenbankverbindungen, Übersetzungen und Konfiguration. Eine ganze Generation
  von Webentwicklern lernte YAML über Rails, lange vor Docker.

* '''Ansible''' (2012) — das Konfigurationsmanagement-Tool wählte YAML als zentrale
  Sprache für Playbooks. Für Systemadministratoren war Ansible der eigentliche
  YAML-Einstieg.

* '''Kubernetes''' (2014) — parallel zu Docker entstanden, ebenfalls YAML für alles.
  Kubernetes hat YAML in der Infrastrukturwelt zementiert.

* '''CI/CD-Systeme''' — GitHub Actions, GitLab CI, Travis CI, CircleCI — alle
  verwenden YAML für Pipeline-Definitionen.

* '''OpenAPI/Swagger''' — API-Dokumentation wird seit Jahren in YAML geschrieben.

Docker Compose hat YAML dann für Heimserver-Betreiber und Administratoren ohne
Rails- oder Ansible-Hintergrund zum Standard gemacht.

=== Kritik in der Fachwelt ===

YAML hat einen schlechten Ruf in Teilen der Entwicklergemeinde — nicht wegen
der Grundidee, sondern wegen der Implementierung.

Die Spezifikation ist notorisch komplex: YAML 1.2 umfasst über 80 Seiten.
Verschiedene Parser verhalten sich bei Grenzfällen unterschiedlich. Und es gibt
berühmte Stolperfallen:

<pre>
# Diese Werte sind KEIN String — YAML interpretiert sie als Boolean:
land: no        # → false
antwort: yes    # → true
aktiv: on       # → true

# Das hier ist kein String — es wird zur Zahl:
version: 1.0    # → Float 1.0, nicht String "1.0"
port: 8080      # → Integer
</pre>

Das bekannteste Beispiel ist das sogenannte '''Norway Problem''': das Länderkürzel
<code>NO</code> wird in älteren YAML-Parsern automatisch zu <code>false</code>
— was dazu geführt hat dass norwegische Entwickler in Konfigurationsdateien
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
noch weit verbreitet.

Das Fazit vieler erfahrener Entwickler: YAML ist für Menschen gut lesbar,
aber für Programme schwer korrekt zu implementieren. Für Konfigurationsdateien
die selten geändert werden ist es hervorragend — für Programme die YAML
generieren oder parsen müssen, ist es eine Quelle von Überraschungen.

----

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

Der häufige Vergleich „YAML ist ein JSON-Dialekt" ist ungenau.
Die präzise Formulierung: '''YAML ist eine Obermenge von JSON.'''

* Jedes gültige JSON ist auch gültiges YAML.
* 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:

JSON:
<pre>
{
  "services": {
    "nextcloud": {
      "image": "nextcloud:latest",
      "restart": "unless-stopped"
    }
  }
}
</pre>

YAML:
<pre>
services:
  nextcloud:
    image: nextcloud:latest
    restart: unless-stopped
</pre>

YAML ist lesbarer — auf Kosten einer strengen Regel:
'''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:

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

=== 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:

<pre>
services:      # Pflicht — definiert die Container
  ...

networks:      # Optional — definiert Netzwerke
  ...

volumes:       # Optional — definiert persistente Datenspeicher
  ...

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

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:

<pre>
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
</pre>

----

== Direktiven im services-Abschnitt ==

=== image ===

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

<pre>
services:
  nextcloud:
    image: lscr.io/linuxserver/nextcloud:latest
</pre>

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.

<pre>
services:
  nextcloud:
    container_name: nextcloud
</pre>

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.

<pre>
restart: unless-stopped
</pre>

{| 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:

<pre>
services:
  mein-dienst:
    build:
      context: ./mein-verzeichnis   # Pfad zum Dockerfile
      dockerfile: Dockerfile.prod   # optional: anderer Dateiname
</pre>

=== ports ===

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

<pre>
services:
  caddy:
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"   # für HTTP/3
</pre>

'''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.

<pre>
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:                         # Docker verwaltet den Speicherort
</pre>

{| 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.

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

Alternativ als Map-Schreibweise:

<pre>
    environment:
      PUID: "1000"
      TZ: Europe/Berlin
</pre>

=== env_file ===

Umgebungsvariablen aus einer externen Datei laden — sinnvoll für Passwörter:

<pre>
services:
  nc-db:
    env_file:
      - .env
</pre>

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

<pre>
MYSQL_ROOT_PASSWORD=sehrgeheim
MYSQL_DATABASE=nextcloud
MYSQL_USER=ncuser
MYSQL_PASSWORD=auchgeheim
</pre>

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

=== networks ===

Netzwerkzugehörigkeit des Containers.

<pre>
services:
  nextcloud:
    networks:
      mein_netzwerk:
        ipv4_address: 172.18.0.20   # feste IP (optional)

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

networks:
  mein_netzwerk:
    external: true                  # Netzwerk existiert bereits
</pre>

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.

<pre>
services:
  nextcloud:
    extra_hosts:
      - "collabora.beispiel.de:172.18.0.6"
</pre>

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.

<pre>
services:
  nextcloud:
    depends_on:
      db:
        condition: service_healthy   # wartet bis Healthcheck grün ist
      redis:
        condition: service_healthy
</pre>

{| 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.

<pre>
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
</pre>

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

=== tmpfs ===

Flüchtige Dateisysteme die nur im RAM leben und beim Container-Stopp verschwinden.

<pre>
services:
  nc-redis:
    tmpfs:
      - /data
      - /tmp
      - /run

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

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.

<pre>
services:
  nextcloud:
    dns:
      - 1.1.1.1    # Cloudflare
      - 9.9.9.9    # Quad9
      - 8.8.8.8    # Google
</pre>

=== command ===

Überschreibt den Standard-Startbefehl des Images.

<pre>
services:
  nc-db:
    command: --transaction-isolation=READ-COMMITTED --binlog-format=ROW
</pre>

=== security_opt und cap_drop / cap_add ===

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

<pre>
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
</pre>

Faustregel:
* <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:

<pre>
services:
  nc-redis:
    read_only: true
    tmpfs:
      - /data
      - /tmp
      - /run
</pre>

----

== Der networks-Abschnitt ==

=== Externes Netzwerk verwenden ===

<pre>
networks:
  mein_netzwerk:
    external: true   # Netzwerk wurde bereits mit docker network create angelegt
</pre>

=== Neues Netzwerk anlegen ===

<pre>
networks:
  mein_netzwerk:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16
          gateway: 172.20.0.1
</pre>

----

== Der volumes-Abschnitt ==

=== Benanntes Volume ===

<pre>
volumes:
  caddy_data:      # Docker verwaltet den Speicherort unter /var/lib/docker/volumes/
  caddy_config:
</pre>

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

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

----

== 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
|-
| <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 || 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, Dienst funktioniert nicht || <code>depends_on</code> ohne <code>condition: service_healthy</code> || Healthcheck ergänzen
|-
| Umgebungsvariable leer || <code>.env</code> liegt nicht im selben Verzeichnis || Pfad prüfen oder <code>env_file</code> explizit angeben
|-
| <code>$$VARIABLE</code> wird nicht aufgelöst || Gewolltes Verhalten || Für Shell-Variablen im Container: <code>$$</code>. Für Compose-Variablen: <code>$</code>
|}

----

== Siehe auch ==

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

[[Kategorie:Docker]]