Docker/Compose/03 compose.yaml: Unterschied zwischen den Versionen

Aus Foxwiki
Wechseln zu:Navigation, Suche
Keine Bearbeitungszusammenfassung
Keine Bearbeitungszusammenfassung
Zeile 1: Zeile 1:
== Datei ''compose.yaml'' ==
== Datei ''compose.yaml'' ==
In diesem Abschnitt fassen wir die wichtigsten Schlüsselwörter zusammen, die in der
In diesem Abschnitt fassen wir die wichtigsten Schlüsselwörter zusammen, die in der Datei compose.yaml vorkommen. Eine vollständige Referenz finden Sie hier:
Datei compose.yaml vorkommen. Eine vollständige Referenz finden Sie hier:
https://docs.docker.com/compose/compose-file Wir beziehen uns in diesem Buch grundsätzlich auf Compose Version 2 gemäß der aktuell geltenden Spezifikation:
https://docs.docker.com/compose/compose-file
https://github.com/compose-spec/compose-spec/blob/master/spec.md compose.yaml beginnt in der Regel mit dem Bezeichner services , auf den eingerückt frei wählbare Namen mehrerer Dienste folgen. Die Eigenschaften jedes Dienstes wer- den, nochmals eingerückt, durch diverse Schlüsselwörter festgelegt:
Wir beziehen uns in diesem Buch grundsätzlich auf Compose Version 2 gemäß der
aktuell geltenden Spezifikation:
https://github.com/compose-spec/compose-spec/blob/master/spec.md
compose.yaml beginnt in der Regel mit dem Bezeichner services , auf den eingerückt
frei wählbare Namen mehrerer Dienste folgen. Die Eigenschaften jedes Dienstes wer-
den, nochmals eingerückt, durch diverse Schlüsselwörter festgelegt:


  # Grunds ä tzlicher Aufbau von compose .yaml
  # Grunds ä tzlicher Aufbau von compose .yaml
Zeile 22: Zeile 16:
  ...
  ...


In manchen Fällen folgen dem Top-Level-Abschnitt services weitere Top-Level-
In manchen Fällen folgen dem Top-Level-Abschnitt services weitere Top-Level-Abschnitte, z. B. volumes, networks oder secrets. Diese sind in der Regel mit gleichnamigen Schlüsselwörtern innerhalb eines Service verbunden. Entsprechende Beispiele folgen in den weiteren Abschnitten.
Abschnitte, z. B. volumes, networks oder secrets. Diese sind in der Regel mit gleichna-
migen Schlüsselwörtern innerhalb eines Service verbunden. Entsprechende Beispiele
folgen in den weiteren Abschnitten.


=== Image oder Dockerfile? ===
=== Image oder Dockerfile? ===
Das Schlüsselwort image gibt an, welches Basis-Image verwendet werden soll. Dabei
Das Schlüsselwort image gibt an, welches Basis-Image verwendet werden soll. Dabei sind Image-Namen in allen Varianten (registryname/reponame/imagename:tag) sowie Image-IDs erlaubt.
sind Image-Namen in allen Varianten (registryname/reponame/imagename:tag) sowie
Image-IDs erlaubt.


  image : ubuntu :22.04
  image : ubuntu :22.04


Sofern Sie nicht docker stack deploy verwenden, können Sie anstelle eines Images
Sofern Sie nicht docker stack deploy verwenden, können Sie anstelle eines Images auch den Pfad zu einem Verzeichnis angeben, in dem sich die Datei Dockerfile befindet:
auch den Pfad zu einem Verzeichnis angeben, in dem sich die Datei Dockerfile be-
findet:


build : verzeichn i s
build : verzeichn i s


docker compose berücksichtigt dann die Angaben in dieser Datei, erzeugt ein entspre-
docker compose berücksichtigt dann die Angaben in dieser Datei, erzeugt ein entsprechendes Image und verwendet dieses als Basis. Wenn Sie das Dockerfile im gleichen Verzeichnis wie compose.yaml gespeichert haben, geben Sie anstelle des Pfads einfach einen Punkt an.
chendes Image und verwendet dieses als Basis. Wenn Sie das Dockerfile im gleichen
Verzeichnis wie compose.yaml gespeichert haben, geben Sie anstelle des Pfads einfach
einen Punkt an.


=== Netzwerke ===
=== Netzwerke ===
docker compose bzw. docker stack deploy richtet für die auszuführenden Container
docker compose bzw. docker stack deploy richtet für die auszuführenden Container bzw. Services automatisch ein eigenes Netzwerk ein. Wenn Sie darüber hinaus zusätzliche Netzwerke einrichten und in Ihren Diensten nutzen möchten, müssen Sie mit dem Top-Level-Schlüsselwort networks eigene Netzwerke definieren und im services-Abschnitt mit einem weiteren networks -Schlüsselwort darauf verweisen.
bzw. Services automatisch ein eigenes Netzwerk ein. Wenn Sie darüber hinaus zusätz-
Im folgenden Beispiel kann der Dienst web mit dem Netzwerk myownnet kommunizieren. Dabei handelt es sich um das in Docker immer verfügbare Host-Netzwerk (siehe docker network ls).
liche Netzwerke einrichten und in Ihren Diensten nutzen möchten, müssen Sie mit
dem Top-Level-Schlüsselwort networks eigene Netzwerke definieren und im services -
Abschnitt mit einem weiteren networks -Schlüsselwort darauf verweisen.
Im folgenden Beispiel kann der Dienst web mit dem Netzwerk myownnet kommunizie-
ren. Dabei handelt es sich um das in Docker immer verfügbare Host-Netzwerk (siehe
docker network ls).


services :
services :
Zeile 61: Zeile 39:
- myownnet
- myownnet


# Top - Level - Abschnitt zur Definiti o n zus ä tzlicher Netzwerk e
# Top-Level-Abschnitt zur Definiti o n zus ä tzlicher Netzwerk e networks :
networks :
myownnet :
myownnet :
external :
external :
Zeile 68: Zeile 45:


=== Netzwerkports ===
=== Netzwerkports ===
Dem Schlüsselwort ports folgt eine Liste von Port-Zuordnungen in der Syntax
Dem Schlüsselwort ports folgt eine Liste von Port-Zuordnungen in der Syntax portnummer (den Port einfach weiterleiten) oder lokal:dienst (einen Port des Dienstes auf einen anderen Port des lokalen Computers umleiten). Die folgende Einstellung macht die Ports 80 und 443 des Docker-Containers bzw. -Service auf den Ports 8080
portnummer (den Port einfach weiterleiten) oder lokal:dienst (einen Port des Dienstes
auf einen anderen Port des lokalen Computers umleiten). Die folgende Einstellung
macht die Ports 80 und 443 des Docker-Containers bzw. -Service auf den Ports 8080
und 8443 des Docker-Hosts zugänglich:
und 8443 des Docker-Hosts zugänglich:


Zeile 78: Zeile 52:
- "8443:44 3 "
- "8443:44 3 "


Wenn Sie einen Port nur innerhalb desjenigen Netzwerks freigeben möchten, das
Wenn Sie einen Port nur innerhalb desjenigen Netzwerks freigeben möchten, das docker compose bzw. docker stack deploy für die Container bzw. Services des Projekts einrichtet, geben Sie diese Ports mit expose an:
docker compose bzw. docker stack deploy für die Container bzw. Services des Projekts
einrichtet, geben Sie diese Ports mit expose an:


expose :
expose :
Zeile 87: Zeile 59:


=== Volumes ===
=== Volumes ===
Dem Schlüsselwort volumes folgt ebenfalls eine Liste, in der Sie angeben, an welchen
Dem Schlüsselwort volumes folgt ebenfalls eine Liste, in der Sie angeben, an welchen lokalen Orten im Docker-Host die Volume-Verzeichnisse des Images abgelegt werden sollen. Der folgende Eintrag bewirkt, dass das Volume/var/lib/mysql des Images auf dem Docker-Host im Verzeichnis/data/db gespeichert werden soll. Dieses Verzeichnis muss bereits existieren, wenn docker compose ausgeführt wird.
lokalen Orten im Docker-Host die Volume-Verzeichnisse des Images abgelegt werden
sollen. Der folgende Eintrag bewirkt, dass das Volume/var/lib/mysql des Images auf
dem Docker-Host im Verzeichnis/data/db gespeichert werden soll. Dieses Verzeich-
nis muss bereits existieren, wenn docker compose ausgeführt wird.


volumes :
volumes :
-/data/db :/var/lib/mysql
-/data/db :/var/lib/mysql


Der Pfad für das lokale Volume-Verzeichnis darf in der Form ./<name> auch relativ
Der Pfad für das lokale Volume-Verzeichnis darf in der Form ./<name> auch relativ zum Ort der Datei compose.yaml angegeben werden. Unter Fedora und RHEL müssen Sie für Volumes, die nicht innerhalb des Standardverzeichnisses für Docker bzw. Podman gespeichert werden (also z. B. nicht in/var/lib/docker ), das zusätzliche Flag :z angeben.
zum Ort der Datei compose.yaml angegeben werden. Unter Fedora und RHEL müssen
Sie für Volumes, die nicht innerhalb des Standardverzeichnisses für Docker bzw. Pod-
man gespeichert werden (also z. B. nicht in/var/lib/docker ), das zusätzliche Flag :z
angeben.


; Volumes im Heimatverzeichnis
; Volumes im Heimatverzeichnis
Zeile 106: Zeile 70:
:* Wenn Sie einen Pfad relativ zum Heimatverzeichnis des aktiven Benutzers wünschen, leiten Sie den Pfad mit ~ ein
:* Wenn Sie einen Pfad relativ zum Heimatverzeichnis des aktiven Benutzers wünschen, leiten Sie den Pfad mit ~ ein


; docker compose
; docker compose interpretiert die bloße Angabe von <name> nicht als relativen Pfad, sondern als Namen für ein benanntes Volume! docker compose erwartet in diesem Fall einen zusätzlichen Top-Level-Abschnitt volumes , in dem die Details des Volumes
interpretiert die bloße Angabe von <name> nicht als relativen Pfad,
sondern als Namen für ein benanntes Volume! docker compose erwartet in diesem
Fall einen zusätzlichen Top-Level-Abschnitt volumes , in dem die Details des Volumes
<name> definiert sind. Ein entsprechendes Beispiel folgt im nächsten Abschnitt.
<name> definiert sind. Ein entsprechendes Beispiel folgt im nächsten Abschnitt.


Beachten Sie, dass auch einzelne Dateien als Volumes betrachtet werden. In diesem
Beachten Sie, dass auch einzelne Dateien als Volumes betrachtet werden. In diesem Fall muss die betreffende lokale Datei bereits existieren. Achten Sie aber darauf, dass Sie nicht Verzeichnisse und Dateien vermischen. Sie können also nicht eine lokale Datei einem Image-Verzeichnis zuordnen oder ein lokales Verzeichnis einer Image-Datei.
Fall muss die betreffende lokale Datei bereits existieren. Achten Sie aber darauf, dass
Sie nicht Verzeichnisse und Dateien vermischen. Sie können also nicht eine lokale
Datei einem Image-Verzeichnis zuordnen oder ein lokales Verzeichnis einer Image-
Datei.


  volumes :
  volumes :
- ./default .conf :/etc/nginx/conf . d/default . conf
-./default .conf :/etc/nginx/conf . d/default . conf


=== UID und GID in lokalen Volumes (Docker Engine unter Linux) ===
=== UID und GID in lokalen Volumes (Docker Engine unter Linux) ===
Wenn Sie ein lokales Verzeichnis in Ihrem Heimatverzeichnis zur Speicherung von
Wenn Sie ein lokales Verzeichnis in Ihrem Heimatverzeichnis zur Speicherung von Volumes verwenden, werden neue, vom Container erzeugte Dateien nicht Ihrem eigenen Benutzer bzw. Ihrer Gruppe zugeordnet. Außerhalb des Docker-Containers können Sie diese Dateien nicht verändern und möglicherweise nicht einmal lesen
Volumes verwenden, werden neue, vom Container erzeugte Dateien nicht Ihrem
eigenen Benutzer bzw. Ihrer Gruppe zugeordnet. Außerhalb des Docker-Containers
können Sie diese Dateien nicht verändern und möglicherweise nicht einmal lesen
(z. B. bei einem Backup).
(z. B. bei einem Backup).
Das hier beschriebene Problem tritt nur auf, wenn Sie unter Linux mit einer Stan-
Das hier beschriebene Problem tritt nur auf, wenn Sie unter Linux mit einer Standardinstallation der Docker Engine arbeiten. Es tritt nicht auf, wenn Sie mit Rootless Docker oder mit Podman arbeiten.
dardinstallation der Docker Engine arbeiten. Es tritt nicht auf, wenn Sie mit Rootless
Docker oder mit Podman arbeiten.
Am einfachsten ist das Problem anhand eines konkreten Beispiels zu verstehen:
Am einfachsten ist das Problem anhand eines konkreten Beispiels zu verstehen:
Die folgende Datei compose.yaml beschreibt einen Alpine-Container, der das gerade
Die folgende Datei compose.yaml beschreibt einen Alpine-Container, der das gerade aktuelle Verzeichnis mit dem/home-Verzeichnis des Containers verbindet. In diesem Verzeichnis wird die neue Datei newfile erzeugt.
aktuelle Verzeichnis mit dem/home-Verzeichnis des Containers verbindet. In diesem
Verzeichnis wird die neue Datei newfile erzeugt.


  # Datei compose . yaml
  # Datei compose . yaml
Zeile 140: Zeile 90:
  image : alpine
  image : alpine
  volumes :
  volumes :
- ./:/home : z
-./:/home : z
  command : [" touch " , "/home/newfile "]
  command : [" touch " , "/home/newfile "]


Wenn Sie das Setup unter Linux ausführen, gehört die neue Datei nicht Ihnen, son-
Wenn Sie das Setup unter Linux ausführen, gehört die neue Datei nicht Ihnen, sondern dem Benutzer root. Das liegt daran, dass der Docker-Dämon mit root-Rechten läuft.
dern dem Benutzer root. Das liegt daran, dass der Docker-Dämon mit root-Rechten
läuft.


  docker compose up
  docker compose up


  ls -l newfile
  ls -l newfile
  -rw - r - -r - - 1 root      root          0 17. Jun 09:46 newfile
  -rw-r--r-- 1 root      root          0 17. Jun 09:46 newfile


Wenn Sie dagegen mit Rootless Docker oder mit Podman arbeiten, gehört die Datei
Wenn Sie dagegen mit Rootless Docker oder mit Podman arbeiten, gehört die Datei Ihnen:
Ihnen:


podman - compose up
podman-compose up


ls -l newfile
ls -l newfile
-rw - r - -r - -. 1 user user            0 17. Jun 09:50 newfile
-rw-r--r--. 1 user user            0 17. Jun 09:50 newfile


Wenn Sie im Zusammenspiel mit Docker und Linux vermeiden möchten, dass neue
Wenn Sie im Zusammenspiel mit Docker und Linux vermeiden möchten, dass neue Dateien root gehören, können Sie compose.yaml um das Schlüsselwort user erweitern und dort eine UID (User Identification Number) oder GID (Group Identification Number) angeben. user legt fest, in welchem Account der Container-Prozess ausgeführt
Dateien root gehören, können Sie compose.yaml um das Schlüsselwort user erweitern
und dort eine UID (User Identification Number) oder GID (Group Identification Num-
ber) angeben. user legt fest, in welchem Account der Container-Prozess ausgeführt


wird. Der Account kann auch durch das Schlüsselwort USER im zugrundeliegenden
wird. Der Account kann auch durch das Schlüsselwort USER im zugrundeliegenden Dockerfile festgelegt werden.
Dockerfile festgelegt werden.


  # Datei compose . yaml
  # Datei compose . yaml
Zeile 173: Zeile 116:
  image : alpine
  image : alpine
  volumes :
  volumes :
- ./:/home : z
-./:/home : z
  command : [" touch " , "/home/newfile "]
  command : [" touch " , "/home/newfile "]
  user : "1000:10 00 "
  user : "1000:10 00 "


Das obige Listing setzt voraus, dass Ihre UID und GID jeweils 1000 ist. Das trifft für
Das obige Listing setzt voraus, dass Ihre UID und GID jeweils 1000 ist. Das trifft für den ersten angelegten Benutzer zu. Allgemeingültiger ist die folgende Variante, die aber voraussetzt, dass Sie die Variable UID_GID vor dem Aufruf von docker compose initialisieren:
den ersten angelegten Benutzer zu. Allgemeingültiger ist die folgende Variante, die
aber voraussetzt, dass Sie die Variable UID_GID vor dem Aufruf von docker compose
initialisieren:


  # in compose . yaml
  # in compose . yaml
Zeile 189: Zeile 129:
  UID_GID =" $ ( id -u ) : $( id -g) " docker compose up
  UID_GID =" $ ( id -u ) : $( id -g) " docker compose up


Leider ist die Vorgehensweise mit user inkompatibel mit podman-compose. Das Script
Leider ist die Vorgehensweise mit user inkompatibel mit podman-compose. Das Script verarbeitet das Schlüsselwort user zwar prinzipiell korrekt, allerdings tritt nun bei der Ausführung des Containers der Fehler permission denied auf.
verarbeitet das Schlüsselwort user zwar prinzipiell korrekt, allerdings tritt nun bei der
Ausführung des Containers der Fehler permission denied auf.


=== Benannte Volumes ===
=== Benannte Volumes ===
Zur Definition benannter Volumes stellen Sie dem Volume-Verzeichnis einfach den
Zur Definition benannter Volumes stellen Sie dem Volume-Verzeichnis einfach den gewünschten Namen (im folgenden Beispiel webdata) voran. Allerdings müssen Sie das Volume ein zweites Mail in der Top-Level-Ebene volumes angeben. Dort können Sie gegebenenfalls besondere Eigenschaften des Volumes festlegen:
gewünschten Namen (im folgenden Beispiel webdata) voran. Allerdings müssen Sie
das Volume ein zweites Mail in der Top-Level-Ebene volumes angeben. Dort können
Sie gegebenenfalls besondere Eigenschaften des Volumes festlegen:


  # Datei compose . yaml im Verzeichn i s test2
  # Datei compose . yaml im Verzeichn i s test2
Zeile 203: Zeile 138:
  nginx :
  nginx :
  volumes :
  volumes :
- webdata :/var/www/html/
-webdata :/var/www/html/
  ...
  ...
   
   
Zeile 209: Zeile 144:
  webdata :
  webdata :


Docker kümmert sich darum, das Volume einzurichten. Der Volume-Name setzt sich
Docker kümmert sich darum, das Volume einzurichten. Der Volume-Name setzt sich aus dem aktuellen Verzeichnisnamen, dem in der Datei compose.yaml angegebenen Namen sowie data_ zusammen. Sofern Sie Docker mit root-Rechten ausführen und das aktuelle Verzeichnis test2 lautet, ergibt sich der folgende Pfad:
aus dem aktuellen Verzeichnisnamen, dem in der Datei compose.yaml angegebenen
Namen sowie data_ zusammen. Sofern Sie Docker mit root-Rechten ausführen und
das aktuelle Verzeichnis test2 lautet, ergibt sich der folgende Pfad:


  /var/lib/docker/volumes/test2_web d a t a/_data
  /var/lib/docker/volumes/test2_web d a t a/_data


Volumes für Services
Volumes für Services In einem Docker-Schwarm entscheidet der Schwarm-Manager, auf welchem Knoten ein Service ausgeführt wird. Der Ort kann sich also jederzeit ändern. Bei der Verwendung von Volumes führt das zu Problemen: Ein beim ersten Ablauf auf Knoten A eingerichtetes Volume existiert ja nicht auf Knoten B, wo der Service vielleicht beim nächsten Mal läuft.
In einem Docker-Schwarm entscheidet der Schwarm-Manager, auf welchem Knoten
ein Service ausgeführt wird. Der Ort kann sich also jederzeit ändern. Bei der Ver-
wendung von Volumes führt das zu Problemen: Ein beim ersten Ablauf auf Knoten
A eingerichtetes Volume existiert ja nicht auf Knoten B, wo der Service vielleicht
beim nächsten Mal läuft.
Um dieses Problem zu umgehen, können Sie in den Deploy-Einstellungen mit deploy.
Um dieses Problem zu umgehen, können Sie in den Deploy-Einstellungen mit deploy.
placement.constraints Regeln festlegen, auf welchem Knoten der Service laufen
placement.constraints Regeln festlegen, auf welchem Knoten der Service laufen soll.
soll.


=== Umgebungsvariablen ===
=== Umgebungsvariablen ===
Dem Schlüsselwort environment folgen wahlweise Key-Value-Paare oder Listenele-
Dem Schlüsselwort environment folgen wahlweise Key-Value-Paare oder Listenelemente in der Form var=wert. Die so definierten Umgebungsvariablen gelten bei der Ausführung des Kommandos im Container. Die beiden folgenden Listings sind gleichwertig:
mente in der Form var=wert. Die so definierten Umgebungsvariablen gelten bei der
Ausführung des Kommandos im Container. Die beiden folgenden Listings sind gleich-
wertig:


  environme n t :
  environme n t :
Zeile 237: Zeile 160:


  environme n t :
  environme n t :
- WORDPRES S _D B _ H OS T = mariadb
-WORDPRES S _D B _ H OS T = mariadb
- WORDPRES S _D B _ N AM E = dockerbu ch
-WORDPRES S _D B _ N AM E = dockerbu ch


Wenn Sie viele Umgebungsvariablen setzen müssen, können Sie die Einstellungen
Wenn Sie viele Umgebungsvariablen setzen müssen, können Sie die Einstellungen mit env_file: dateiname auch aus einer Datei lesen.
mit env_file: dateiname auch aus einer Datei lesen.


=== Kommandoausführung ===
=== Kommandoausführung ===
Normalerweise wird in Containern bzw. Services das Kommando ausgeführt, das im
Normalerweise wird in Containern bzw. Services das Kommando ausgeführt, das im Image durch ENTRYPOINT und/oder CMD vorgegeben ist (siehe auch den Abschnitt »Container-Startkommando« in Abschnitt 4.2, »Dockerfile-Syntax«). Bei einem Apache-Image wird das ein Startkommando für den Webserver sein, bei einem MySQL-Image der Dienst des MySQL-Servers etc.
Image durch ENTRYPOINT und/oder CMD vorgegeben ist (siehe auch den Abschnitt »Con-
tainer-Startkommando« in Abschnitt 4.2, »Dockerfile-Syntax«). Bei einem Apache-
Image wird das ein Startkommando für den Webserver sein, bei einem MySQL-Image
der Dienst des MySQL-Servers etc.


Wenn davon abweichend ein anderes Kommando ausgeführt werden soll, geben Sie
Wenn davon abweichend ein anderes Kommando ausgeführt werden soll, geben Sie dieses mit den Schlüsselwörtern entrypoint und/oder command an. Beachten Sie, dass Sie Kommandos, die aus mehreren Teilen zusammengesetzt sind, entweder als Liste oder in der Form ["teil1", "teil2", "teil3"] übergeben müssen.
dieses mit den Schlüsselwörtern entrypoint und/oder command an. Beachten Sie, dass
Sie Kommandos, die aus mehreren Teilen zusammengesetzt sind, entweder als Liste
oder in der Form ["teil1", "teil2", "teil3"] übergeben müssen.


entrypoin t : [" some -script . sh "]
entrypoin t : [" some -script . sh "]
command :    ["/bin/bash "]
command :    ["/bin/bash "]


# mehrteil i g e s Kommando
# mehrteil i g e s Kommando command : [" php " , " -a "]
command : [" php " , " -a "]


# gleichwe r t i g
# gleichwe r t i g command :
command :
- " php "
- " php "
- " -a "
- " -a "


=== Restart-Verhalten (Docker-spezifisch) ===
=== Restart-Verhalten (Docker-spezifisch) ===
Bei Containern, die mit docker compose erzeugt werden, können Sie mit dem Schlüs-
Bei Containern, die mit docker compose erzeugt werden, können Sie mit dem Schlüsselwort restart einstellen, ob sie bei einem Rechnerneustart oder nach einem Fehler automatisch neu gestartet werden sollen. Das Defaultverhalten lautet no. Die anderen zulässigen Einstellungen lauten always, on-failure und unless-stopped . (Eine genaue Erläuterung der Schlüsselwörter finden Sie in Abschnitt 6.6, »Container automatisch starten«.)
selwort restart einstellen, ob sie bei einem Rechnerneustart oder nach einem Fehler
automatisch neu gestartet werden sollen. Das Defaultverhalten lautet no. Die anderen
zulässigen Einstellungen lauten always, on-failure und unless-stopped . (Eine genaue
Erläuterung der Schlüsselwörter finden Sie in Abschnitt 6.6, »Container automatisch
starten«.)


restart : always
restart : always


Das restart -Schlüsselwort wird von docker stack deploy ignoriert. Für Stack-Services
Das restart -Schlüsselwort wird von docker stack deploy ignoriert. Für Stack-Services gilt standardmäßig, dass sie bei Bedarf automatisch neu gestartet werden. Davon abweichende Einstellungen können Sie mit deploy.restart_policy festlegen (siehe
gilt standardmäßig, dass sie bei Bedarf automatisch neu gestartet werden. Davon
abweichende Einstellungen können Sie mit deploy.restart_policy festlegen (siehe
»Deploy-Einstellungen«).
»Deploy-Einstellungen«).


=== Deploy-Einstellungen ===
=== Deploy-Einstellungen ===
Das Schlüsselwort deploy steuert, wie Services durch docker stack deploy eingerich-
Das Schlüsselwort deploy steuert, wie Services durch docker stack deploy eingerichtet werden. Diese Einstellungen gelten nur für den Schwarmmodus. docker compose ignoriert das deploy-Schlüsselwort und alle von ihm abgeleiteten Einstellungen!
tet werden. Diese Einstellungen gelten nur für den Schwarmmodus. docker compose
ignoriert das deploy-Schlüsselwort und alle von ihm abgeleiteten Einstellungen!
Die folgende Liste fasst die wichtigsten Schlüsselwörter zusammen:
Die folgende Liste fasst die wichtigsten Schlüsselwörter zusammen:


deploy.mode gibt an, wie der Service ausgeführt wird. Die Defaulteinstellung lautet
deploy.mode gibt an, wie der Service ausgeführt wird. Die Defaulteinstellung lautet replicated . Damit kann angegeben werden, wie viele Instanzen ausgeführt werden.
replicated . Damit kann angegeben werden, wie viele Instanzen ausgeführt werden.
Der Schwarm-Manager entscheidet dann, auf welchen Docker-Rechnern die Instanzen gestartet werden.
Der Schwarm-Manager entscheidet dann, auf welchen Docker-Rechnern die Instan-
zen gestartet werden.


Die alternative Einstellung global bestimmt, dass auf jedem Knoten im Schwarm
Die alternative Einstellung global bestimmt, dass auf jedem Knoten im Schwarm exakt eine Instanz des Service ausgeführt werden soll.
exakt eine Instanz des Service ausgeführt werden soll.
deploy.placement.constraint legt eine Liste von Regeln fest, die bestimmt, auf welchem Knoten der Service laufen soll. Die folgenden Zeilen geben Beispiele für mögliche Regeln:
deploy.placement.constraint legt eine Liste von Regeln fest, die bestimmt, auf wel-
chem Knoten der Service laufen soll. Die folgenden Zeilen geben Beispiele für
mögliche Regeln:


- node . id == <xxxx >
-node . id == <xxxx >
- node . hostname == <name >
-node . hostname == <name >
- node . role == manager | worker
-node . role == manager | worker


deploy.replicas gibt an, wie viele Instanzen des Service gleichzeitig laufen sollen
deploy.replicas gibt an, wie viele Instanzen des Service gleichzeitig laufen sollen
(normalerweise nur eine Instanz).
(normalerweise nur eine Instanz).
deploy.resources.limits.cpus limitiert die CPU-Nutzung des Service. Die Einstel-
deploy.resources.limits.cpus limitiert die CPU-Nutzung des Service. Die Einstellung 0.25 bedeutet, dass der Service ein CPU-Core durchschnittlich zu 25 % auslasten darf.
lung 0.25 bedeutet, dass der Service ein CPU-Core durchschnittlich zu 25 % auslas-
deploy.resources.limits.memory legt eine Obergrenze für den Speicherbedarf des Service fest.
ten darf.
deploy.restart_policy.condition: any|on-failure|none gibt an, unter welchen Umständen ein Service automatisch neu gestartet werden soll. Standardmäßig gilt any.
deploy.resources.limits.memory legt eine Obergrenze für den Speicherbedarf des
deploy.restart_policy.delay bestimmt, wie viele Sekunden Docker warten soll, bevor es einen Service neu startet (standardmäßig 0).
Service fest.
deploy.restart_policy.max_attempts limitiert die Anzahl der Neustarts. (Standardmäßig gibt es kein Limit.)
deploy.restart_policy.condition: any|on-failure|none gibt an, unter welchen
Umständen ein Service automatisch neu gestartet werden soll. Standardmäßig
gilt any.
deploy.restart_policy.delay bestimmt, wie viele Sekunden Docker warten soll,
bevor es einen Service neu startet (standardmäßig 0).
deploy.restart_policy.max_attempts limitiert die Anzahl der Neustarts. (Standard-
mäßig gibt es kein Limit.)


In compose.yaml müssen die Einstellungen wie üblich durch Einrückungen formuliert
In compose.yaml müssen die Einstellungen wie üblich durch Einrückungen formuliert werden:
werden:


  services :
  services :
Zeile 326: Zeile 217:
  placement :
  placement :
  constrai n t s :
  constrai n t s :
  - node . hostname == " dockerhos t 7 "
  -node . hostname == " dockerhos t 7 "
  replicas : 5
  replicas : 5
  resources :
  resources :
Zeile 333: Zeile 224:
  memory : 50 M
  memory : 50 M
  restart_p o l i cy :
  restart_p o l i cy :
  conditio n : on - failure
  conditio n : on-failure
  delay : 2 s
  delay : 2 s

Version vom 17. November 2026, 15:59 Uhr

Datei compose.yaml

In diesem Abschnitt fassen wir die wichtigsten Schlüsselwörter zusammen, die in der Datei compose.yaml vorkommen. Eine vollständige Referenz finden Sie hier: https://docs.docker.com/compose/compose-file Wir beziehen uns in diesem Buch grundsätzlich auf Compose Version 2 gemäß der aktuell geltenden Spezifikation: https://github.com/compose-spec/compose-spec/blob/master/spec.md compose.yaml beginnt in der Regel mit dem Bezeichner services , auf den eingerückt frei wählbare Namen mehrerer Dienste folgen. Die Eigenschaften jedes Dienstes wer- den, nochmals eingerückt, durch diverse Schlüsselwörter festgelegt:

# Grunds ä tzlicher Aufbau von compose .yaml
services :
dienstna m e 1 :
schl ü sselwort 1 : einstell u n g1
schl ü sselwort 2 : einstell u n g2
...
dienstna m e 2 :
schl ü sselwort 1 : einstell u n g1
schl ü sselwort 2 : einstell u n g2
...

In manchen Fällen folgen dem Top-Level-Abschnitt services weitere Top-Level-Abschnitte, z. B. volumes, networks oder secrets. Diese sind in der Regel mit gleichnamigen Schlüsselwörtern innerhalb eines Service verbunden. Entsprechende Beispiele folgen in den weiteren Abschnitten.

Image oder Dockerfile?

Das Schlüsselwort image gibt an, welches Basis-Image verwendet werden soll. Dabei sind Image-Namen in allen Varianten (registryname/reponame/imagename:tag) sowie Image-IDs erlaubt.

image : ubuntu :22.04

Sofern Sie nicht docker stack deploy verwenden, können Sie anstelle eines Images auch den Pfad zu einem Verzeichnis angeben, in dem sich die Datei Dockerfile befindet:

build : verzeichn i s

docker compose berücksichtigt dann die Angaben in dieser Datei, erzeugt ein entsprechendes Image und verwendet dieses als Basis. Wenn Sie das Dockerfile im gleichen Verzeichnis wie compose.yaml gespeichert haben, geben Sie anstelle des Pfads einfach einen Punkt an.

Netzwerke

docker compose bzw. docker stack deploy richtet für die auszuführenden Container bzw. Services automatisch ein eigenes Netzwerk ein. Wenn Sie darüber hinaus zusätzliche Netzwerke einrichten und in Ihren Diensten nutzen möchten, müssen Sie mit dem Top-Level-Schlüsselwort networks eigene Netzwerke definieren und im services-Abschnitt mit einem weiteren networks -Schlüsselwort darauf verweisen. Im folgenden Beispiel kann der Dienst web mit dem Netzwerk myownnet kommunizieren. Dabei handelt es sich um das in Docker immer verfügbare Host-Netzwerk (siehe docker network ls).

services : web : ... networks : - myownnet

  1. Top-Level-Abschnitt zur Definiti o n zus ä tzlicher Netzwerk e networks :

myownnet : external : name : host

Netzwerkports

Dem Schlüsselwort ports folgt eine Liste von Port-Zuordnungen in der Syntax portnummer (den Port einfach weiterleiten) oder lokal:dienst (einen Port des Dienstes auf einen anderen Port des lokalen Computers umleiten). Die folgende Einstellung macht die Ports 80 und 443 des Docker-Containers bzw. -Service auf den Ports 8080 und 8443 des Docker-Hosts zugänglich:

ports : - "8080:80 " - "8443:44 3 "

Wenn Sie einen Port nur innerhalb desjenigen Netzwerks freigeben möchten, das docker compose bzw. docker stack deploy für die Container bzw. Services des Projekts einrichtet, geben Sie diese Ports mit expose an:

expose : - "7500" - "7501"

Volumes

Dem Schlüsselwort volumes folgt ebenfalls eine Liste, in der Sie angeben, an welchen lokalen Orten im Docker-Host die Volume-Verzeichnisse des Images abgelegt werden sollen. Der folgende Eintrag bewirkt, dass das Volume/var/lib/mysql des Images auf dem Docker-Host im Verzeichnis/data/db gespeichert werden soll. Dieses Verzeichnis muss bereits existieren, wenn docker compose ausgeführt wird.

volumes : -/data/db :/var/lib/mysql

Der Pfad für das lokale Volume-Verzeichnis darf in der Form ./<name> auch relativ zum Ort der Datei compose.yaml angegeben werden. Unter Fedora und RHEL müssen Sie für Volumes, die nicht innerhalb des Standardverzeichnisses für Docker bzw. Podman gespeichert werden (also z. B. nicht in/var/lib/docker ), das zusätzliche Flag :z angeben.

Volumes im Heimatverzeichnis
Der lokale Volume-Pfad (also der Teil vor dem Doppelpunkt) wird relativ zur Datei compose.yaml ausgewertet
  • Wenn Sie einen Pfad relativ zum Heimatverzeichnis des aktiven Benutzers wünschen, leiten Sie den Pfad mit ~ ein
docker compose interpretiert die bloße Angabe von <name> nicht als relativen Pfad, sondern als Namen für ein benanntes Volume! docker compose erwartet in diesem Fall einen zusätzlichen Top-Level-Abschnitt volumes , in dem die Details des Volumes

<name> definiert sind. Ein entsprechendes Beispiel folgt im nächsten Abschnitt.

Beachten Sie, dass auch einzelne Dateien als Volumes betrachtet werden. In diesem Fall muss die betreffende lokale Datei bereits existieren. Achten Sie aber darauf, dass Sie nicht Verzeichnisse und Dateien vermischen. Sie können also nicht eine lokale Datei einem Image-Verzeichnis zuordnen oder ein lokales Verzeichnis einer Image-Datei.

volumes :

-./default .conf :/etc/nginx/conf . d/default . conf

UID und GID in lokalen Volumes (Docker Engine unter Linux)

Wenn Sie ein lokales Verzeichnis in Ihrem Heimatverzeichnis zur Speicherung von Volumes verwenden, werden neue, vom Container erzeugte Dateien nicht Ihrem eigenen Benutzer bzw. Ihrer Gruppe zugeordnet. Außerhalb des Docker-Containers können Sie diese Dateien nicht verändern und möglicherweise nicht einmal lesen (z. B. bei einem Backup). Das hier beschriebene Problem tritt nur auf, wenn Sie unter Linux mit einer Standardinstallation der Docker Engine arbeiten. Es tritt nicht auf, wenn Sie mit Rootless Docker oder mit Podman arbeiten. Am einfachsten ist das Problem anhand eines konkreten Beispiels zu verstehen: Die folgende Datei compose.yaml beschreibt einen Alpine-Container, der das gerade aktuelle Verzeichnis mit dem/home-Verzeichnis des Containers verbindet. In diesem Verzeichnis wird die neue Datei newfile erzeugt.

# Datei compose . yaml
services :
secrette s t :
image : alpine
volumes :

-./:/home : z

command : [" touch " , "/home/newfile "]

Wenn Sie das Setup unter Linux ausführen, gehört die neue Datei nicht Ihnen, sondern dem Benutzer root. Das liegt daran, dass der Docker-Dämon mit root-Rechten läuft.

docker compose up
ls -l newfile
-rw-r--r-- 1 root      root          0 17. Jun 09:46 newfile

Wenn Sie dagegen mit Rootless Docker oder mit Podman arbeiten, gehört die Datei Ihnen:

podman-compose up

ls -l newfile -rw-r--r--. 1 user user 0 17. Jun 09:50 newfile

Wenn Sie im Zusammenspiel mit Docker und Linux vermeiden möchten, dass neue Dateien root gehören, können Sie compose.yaml um das Schlüsselwort user erweitern und dort eine UID (User Identification Number) oder GID (Group Identification Number) angeben. user legt fest, in welchem Account der Container-Prozess ausgeführt

wird. Der Account kann auch durch das Schlüsselwort USER im zugrundeliegenden Dockerfile festgelegt werden.

# Datei compose . yaml
services :
secrette s t :
image : alpine
volumes :

-./:/home : z

command : [" touch " , "/home/newfile "]
user : "1000:10 00 "

Das obige Listing setzt voraus, dass Ihre UID und GID jeweils 1000 ist. Das trifft für den ersten angelegten Benutzer zu. Allgemeingültiger ist die folgende Variante, die aber voraussetzt, dass Sie die Variable UID_GID vor dem Aufruf von docker compose initialisieren:

# in compose . yaml
...
user : $ { UID_GID }

Sie müssen nun docker compose wie folgt aufrufen:

UID_GID =" $ ( id -u ) : $( id -g) " docker compose up

Leider ist die Vorgehensweise mit user inkompatibel mit podman-compose. Das Script verarbeitet das Schlüsselwort user zwar prinzipiell korrekt, allerdings tritt nun bei der Ausführung des Containers der Fehler permission denied auf.

Benannte Volumes

Zur Definition benannter Volumes stellen Sie dem Volume-Verzeichnis einfach den gewünschten Namen (im folgenden Beispiel webdata) voran. Allerdings müssen Sie das Volume ein zweites Mail in der Top-Level-Ebene volumes angeben. Dort können Sie gegebenenfalls besondere Eigenschaften des Volumes festlegen:

# Datei compose . yaml im Verzeichn i s test2
services :
nginx :
volumes :

-webdata :/var/www/html/

...

volumes :
webdata :

Docker kümmert sich darum, das Volume einzurichten. Der Volume-Name setzt sich aus dem aktuellen Verzeichnisnamen, dem in der Datei compose.yaml angegebenen Namen sowie data_ zusammen. Sofern Sie Docker mit root-Rechten ausführen und das aktuelle Verzeichnis test2 lautet, ergibt sich der folgende Pfad:

/var/lib/docker/volumes/test2_web d a t a/_data

Volumes für Services In einem Docker-Schwarm entscheidet der Schwarm-Manager, auf welchem Knoten ein Service ausgeführt wird. Der Ort kann sich also jederzeit ändern. Bei der Verwendung von Volumes führt das zu Problemen: Ein beim ersten Ablauf auf Knoten A eingerichtetes Volume existiert ja nicht auf Knoten B, wo der Service vielleicht beim nächsten Mal läuft. Um dieses Problem zu umgehen, können Sie in den Deploy-Einstellungen mit deploy. placement.constraints Regeln festlegen, auf welchem Knoten der Service laufen soll.

Umgebungsvariablen

Dem Schlüsselwort environment folgen wahlweise Key-Value-Paare oder Listenelemente in der Form var=wert. Die so definierten Umgebungsvariablen gelten bei der Ausführung des Kommandos im Container. Die beiden folgenden Listings sind gleichwertig:

environme n t :
WORDPRES S _ D B_ H O S T : mariadb
WORDPRES S _ D B_ N A M E : dockerbu c h
environme n t :

-WORDPRES S _D B _ H OS T = mariadb -WORDPRES S _D B _ N AM E = dockerbu ch

Wenn Sie viele Umgebungsvariablen setzen müssen, können Sie die Einstellungen mit env_file: dateiname auch aus einer Datei lesen.

Kommandoausführung

Normalerweise wird in Containern bzw. Services das Kommando ausgeführt, das im Image durch ENTRYPOINT und/oder CMD vorgegeben ist (siehe auch den Abschnitt »Container-Startkommando« in Abschnitt 4.2, »Dockerfile-Syntax«). Bei einem Apache-Image wird das ein Startkommando für den Webserver sein, bei einem MySQL-Image der Dienst des MySQL-Servers etc.

Wenn davon abweichend ein anderes Kommando ausgeführt werden soll, geben Sie dieses mit den Schlüsselwörtern entrypoint und/oder command an. Beachten Sie, dass Sie Kommandos, die aus mehreren Teilen zusammengesetzt sind, entweder als Liste oder in der Form ["teil1", "teil2", "teil3"] übergeben müssen.

entrypoin t : [" some -script . sh "] command : ["/bin/bash "]

  1. mehrteil i g e s Kommando command : [" php " , " -a "]
  1. gleichwe r t i g command :

- " php " - " -a "

Restart-Verhalten (Docker-spezifisch)

Bei Containern, die mit docker compose erzeugt werden, können Sie mit dem Schlüsselwort restart einstellen, ob sie bei einem Rechnerneustart oder nach einem Fehler automatisch neu gestartet werden sollen. Das Defaultverhalten lautet no. Die anderen zulässigen Einstellungen lauten always, on-failure und unless-stopped . (Eine genaue Erläuterung der Schlüsselwörter finden Sie in Abschnitt 6.6, »Container automatisch starten«.)

restart : always

Das restart -Schlüsselwort wird von docker stack deploy ignoriert. Für Stack-Services gilt standardmäßig, dass sie bei Bedarf automatisch neu gestartet werden. Davon abweichende Einstellungen können Sie mit deploy.restart_policy festlegen (siehe »Deploy-Einstellungen«).

Deploy-Einstellungen

Das Schlüsselwort deploy steuert, wie Services durch docker stack deploy eingerichtet werden. Diese Einstellungen gelten nur für den Schwarmmodus. docker compose ignoriert das deploy-Schlüsselwort und alle von ihm abgeleiteten Einstellungen! Die folgende Liste fasst die wichtigsten Schlüsselwörter zusammen:

deploy.mode gibt an, wie der Service ausgeführt wird. Die Defaulteinstellung lautet replicated . Damit kann angegeben werden, wie viele Instanzen ausgeführt werden. Der Schwarm-Manager entscheidet dann, auf welchen Docker-Rechnern die Instanzen gestartet werden.

Die alternative Einstellung global bestimmt, dass auf jedem Knoten im Schwarm exakt eine Instanz des Service ausgeführt werden soll. deploy.placement.constraint legt eine Liste von Regeln fest, die bestimmt, auf welchem Knoten der Service laufen soll. Die folgenden Zeilen geben Beispiele für mögliche Regeln:

-node . id == <xxxx > -node . hostname == <name > -node . role == manager | worker

deploy.replicas gibt an, wie viele Instanzen des Service gleichzeitig laufen sollen (normalerweise nur eine Instanz). deploy.resources.limits.cpus limitiert die CPU-Nutzung des Service. Die Einstellung 0.25 bedeutet, dass der Service ein CPU-Core durchschnittlich zu 25 % auslasten darf. deploy.resources.limits.memory legt eine Obergrenze für den Speicherbedarf des Service fest. deploy.restart_policy.condition: any|on-failure|none gibt an, unter welchen Umständen ein Service automatisch neu gestartet werden soll. Standardmäßig gilt any. deploy.restart_policy.delay bestimmt, wie viele Sekunden Docker warten soll, bevor es einen Service neu startet (standardmäßig 0). deploy.restart_policy.max_attempts limitiert die Anzahl der Neustarts. (Standardmäßig gibt es kein Limit.)

In compose.yaml müssen die Einstellungen wie üblich durch Einrückungen formuliert werden:

services :
nginx :
image : nginx : alpine
deploy :
placement :
constrai n t s :
-node . hostname == " dockerhos t 7 "
replicas : 5
resources :
limits :
cpus : '0.25 '
memory : 50 M
restart_p o l i cy :
conditio n : on-failure
delay : 2 s