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

Aus Foxwiki
Wechseln zu:Navigation, Suche
Keine Bearbeitungszusammenfassung
 
(51 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
== Datei ''compose.yaml'' ==
'''Docker/Compose/03 compose.yaml''' - Schlüsselwörter für die Datei ''[[compose.yaml]]'' von ''[[docker compose]]''
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
=== Beschreibung ===
services :
; compose.yaml
dienstna m e 1 :
* Beginnt in der Regel mit dem Bezeichner ''services''
schl ü sselwort 1 : einstell u n g1
* auf den eingerückt frei wählbare Namen mehrerer Dienste folgen
schl ü sselwort 2 : einstell u n g2
* Eigenschaften eines Dienstes
...
** Nochmals eingerückt, durch Schlüsselwörter festgelegt


dienstna m e 2 :
; Schema
schl ü sselwort 1 : einstell u n g1
<syntaxhighlight lang="yaml" highlight="1" line copy>
schl ü sselwort 2 : einstell u n g2
# Grundsätzlicher Aufbau von compose.yaml
...
services:
  dienstname1:
    schlüsselwort1: einstellung1
    schlüsselwort2: einstellung2
    ...


In manchen Fällen folgen dem Top-Level-Abschnitt services weitere Top-Level-
  dienstname2:
Abschnitte, z. B. volumes, networks oder secrets. Diese sind in der Regel mit gleichna-
    schlüsselwort1: einstellung1
migen Schlüsselwörtern innerhalb eines Service verbunden. Entsprechende Beispiele
    schlüsselwort2: einstellung2
folgen in den weiteren Abschnitten.
    ...
</syntaxhighlight>


=== Image oder Dockerfile? ===
; Top-Level-Abschnitte
Das Schlüsselwort image gibt an, welches Basis-Image verwendet werden soll. Dabei
In manchen Fällen folgen dem Top-Level-Abschnitt ''services'' weitere Top-Level-Abschnitte, z.&nbsp;B.&nbsp;''volumes'', ''networks'' oder ''secrets''
sind Image-Namen in allen Varianten (registryname/reponame/imagename:tag) sowie
* Diese sind in der Regel mit gleichnamigen Schlüsselwörtern innerhalb eines Service verbunden
Image-IDs erlaubt.


image : ubuntu :22.04
; Dokumentation
:Vollständige Referenz
:* https://docs.docker.com/compose/compose-file
: Compose Version 2 Spezifikation
:* https://github.com/compose-spec/compose-spec/blob/master/spec.md


Sofern Sie nicht docker stack deploy verwenden, können Sie anstelle eines Images
=== Image oder Dockerfile ===
auch den Pfad zu einem Verzeichnis angeben, in dem sich die Datei Dockerfile be-
Das Schlüsselwort image gibt an, welches Basis-Image verwendet werden soll
findet:
* Dabei sind Image-Namen in allen Varianten (registryname/reponame/imagename:tag) sowie Image-IDs erlaubt
<syntaxhighlight lang="yaml" highlight="" copy>
image: ubuntu:22.04
</syntaxhighlight>


build : verzeichn i s
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


docker compose berücksichtigt dann die Angaben in dieser Datei, erzeugt ein entspre-
<syntaxhighlight lang="yaml" highlight="">
chendes Image und verwendet dieses als Basis. Wenn Sie das Dockerfile im gleichen
build: verzeichnis
Verzeichnis wie compose.yaml gespeichert haben, geben Sie anstelle des Pfads einfach
</syntaxhighlight>
einen Punkt an.
 
; docker compose
berücksichtigt 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 ===
=== Netzwerke ===
docker compose bzw. docker stack deploy richtet für die auszuführenden Container
''docker compose'' und ''docker stack deploy'' richtet für die auszuführenden Container oder Services automatisch ein eigenes Netzwerk ein
bzw. Services automatisch ein eigenes Netzwerk ein. Wenn Sie darüber hinaus zusätz-
 
liche Netzwerke einrichten und in Ihren Diensten nutzen möchten, müssen Sie mit
; Zusätzliche Netzwerk
dem Top-Level-Schlüsselwort networks eigene Netzwerke definieren und im services -
Wenn Sie darüber hinaus zusätzliche Netzwerke einrichten und in Ihren Diensten nutzen möchten
Abschnitt mit einem weiteren networks -Schlüsselwort darauf verweisen.
* Müssen Sie mit dem Top-Level-Schlüsselwort networks eigene Netzwerke definieren und  
Im folgenden Beispiel kann der Dienst web mit dem Netzwerk myownnet kommunizie-
* Im Services-Abschnitt mit einem weiteren networks-Schlüsselwort darauf verweisen
ren. Dabei handelt es sich um das in Docker immer verfügbare Host-Netzwerk (siehe
 
docker network ls).
; Beispiel
Ein Dienst ''web'' kann mit dem Netzwerk ''myownnet'' kommunizieren
* Dabei handelt es sich um das in Docker immer verfügbare Host-Netzwerk
 
Siehe auch
docker network ls


services :
<syntaxhighlight lang="yaml" highlight="0" line>
web :
services:
...
  web:
networks :
  ...
- myownnet
  networks:
    - myownnet


# Top - Level - Abschnitt zur Definiti o n zus ä tzlicher Netzwerk e
# Top-Level-Abschnitt zur Definition zusätzlicher Netzwerke
networks :
networks:
myownnet :
  myownnet:
external :
  external:
name : host
  name: host
</syntaxhighlight>


=== 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
* portnummer (den Port einfach weiterleiten) oder  
auf einen anderen Port des lokalen Computers umleiten). Die folgende Einstellung
* ''lokal:dienst'' (einen Port des Dienstes auf einen anderen Port des lokalen Computers umleiten)
macht die Ports 80 und 443 des Docker-Containers bzw. -Service auf den Ports 8080
und 8443 des Docker-Hosts zugänglich:


ports :
Folgendes macht die Ports 80 und 443 des Docker-Containers oder -Service auf den Ports 8080 und 8443 des Docker-Hosts zugänglich
- "8080:80 "
<syntaxhighlight lang="yaml" highlight="" line>
- "8443:44 3 "
ports:
  - "8080:80"
  - "8443:443"
</syntaxhighlight>


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'' oder ''docker stack deploy'' für die Container oder 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 :
<syntaxhighlight lang="yaml" highlight="" line>
- "7500"
expose:
- "7501"
- "7500"
- "7501"
</syntaxhighlight>


=== 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.  
lokalen Orten im Docker-Host die Volume-Verzeichnisse des Images abgelegt werden
* Der folgende Eintrag bewirkt, dass das Volume /var/lib/mysql des Images auf dem Docker-Host im Verzeichnis /data/db gespeichert werden soll
sollen. Der folgende Eintrag bewirkt, dass das Volume/var/lib/mysql des Images auf
* Dieses Verzeichnis muss bereits existieren, wenn docker compose ausgeführt wird.
dem Docker-Host im Verzeichnis/data/db gespeichert werden soll. Dieses Verzeich-
<syntaxhighlight lang="yaml" highlight="" line>
nis muss bereits existieren, wenn docker compose ausgeführt wird.
volumes:
  - /data/db:/var/lib/mysql
</syntaxhighlight>


volumes :
Der Pfad für das lokale Volume-Verzeichnis darf in der Form ./<name> auch relativ zum Ort der Datei compose.yaml angegeben werden
-/data/db :/var/lib/mysql


Der Pfad für das lokale Volume-Verzeichnis darf in der Form ./<name> auch relativ
; Fedora und RHEL  
zum Ort der Datei compose.yaml angegeben werden. Unter Fedora und RHEL müssen
: Hier müssen Sie für Volumes, die nicht innerhalb des Standardverzeichnisses für Docker oder Podman gespeichert werden (also z.&nbsp;B.&nbsp; nicht in /var/lib/docker), das zusätzliche Flag :z angeben
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 117:
:* 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,
interpretiert die bloße Angabe von <name> nicht als relativen Pfad
sondern als Namen für ein benanntes Volume! docker compose erwartet in diesem
* sondern als Namen für ein benanntes Volume!
Fall einen zusätzlichen Top-Level-Abschnitt volumes , in dem die Details des Volumes
* 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
 
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


Beachten Sie, dass auch einzelne Dateien als Volumes betrachtet werden. In diesem
<syntaxhighlight lang="yaml" highlight="" line>
Fall muss die betreffende lokale Datei bereits existieren. Achten Sie aber darauf, dass
volumes:
Sie nicht Verzeichnisse und Dateien vermischen. Sie können also nicht eine lokale
- ./default.conf:/etc/nginx/conf.d/default.conf
Datei einem Image-Verzeichnis zuordnen oder ein lokales Verzeichnis einer Image-
</syntaxhighlight>
Datei.


volumes :
=== Benuter/Gruppen in 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 oder Ihrer Gruppe zugeordnet.
* Außerhalb des Docker-Containers können Sie diese Dateien nicht verändern und möglicherweise nicht einmal lesen (z.&nbsp;B.&nbsp; bei einem Backup).


=== UID und GID in lokalen Volumes (Docker Engine unter Linux) ===
Das hier beschriebene Problem tritt nur auf, wenn Sie unter Linux mit einer Standardinstallation der Docker Engine arbeiten.  
Wenn Sie ein lokales Verzeichnis in Ihrem Heimatverzeichnis zur Speicherung von
* Es tritt nicht auf, wenn Sie mit Rootless Docker oder mit Podman arbeiten.
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 Stan-
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:
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
; Beispiel
services :
Folgende Datei beschreibt einen Alpine-Container, der das gerade aktuelle Verzeichnis mit dem /home-Verzeichnis des Containers verbindet
secrette s t :
* In diesem Verzeichnis wird die neue Datei newfile erzeugt
image : alpine
volumes :
- ./:/home : z
command : [" touch " , "/home/newfile "]


Wenn Sie das Setup unter Linux ausführen, gehört die neue Datei nicht Ihnen, son-
<syntaxhighlight lang="yaml" highlight="" line>
dern dem Benutzer root. Das liegt daran, dass der Docker-Dämon mit root-Rechten
# Datei compose.yaml
läuft.
services:
  secrettest:
    image: alpine
    volumes:
      - ./:/home:z
    command: ["touch","/home/newfile"]
</syntaxhighlight>


docker compose up
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
<syntaxhighlight lang="bash" highlight="1" copy>
docker compose up
</syntaxhighlight>
<syntaxhighlight lang="bash" highlight="1" copy>
ls -l newfile
<syntaxhighlight lang="bash" highlight="">
-rw-r--r-- 1 root      root          0 17. Jun 09:46 newfile
</syntaxhighlight>


ls -l newfile
Wenn Sie dagegen mit Rootless Docker oder mit Podman arbeiten, gehört die Datei Ihnen
-rw - r - -r - - 1 root      root          0 17. Jun 09:46 newfile
<syntaxhighlight lang="bash" highlight="1" copy>
podman-compose up
</syntaxhighlight>


Wenn Sie dagegen mit Rootless Docker oder mit Podman arbeiten, gehört die Datei
<syntaxhighlight lang="bash" highlight="1" copy>
Ihnen:
ls -l newfile
</syntaxhighlight>
<syntaxhighlight lang="bash" highlight="">
-rw-r--r--. 1 user user            0 17. Jun 09:50 newfile
</syntaxhighlight>


podman - compose up
; Zusammenspiel Docker und Linux
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.


ls -l newfile
<syntaxhighlight lang="yaml" highlight="" line>
-rw - r - -r - -. 1 user user            0 17. Jun 09:50 newfile
# Datei compose.yaml
services:
  secrettest:
    image: alpine
    volumes:
      - ./:/home:z
    command: ["touch","/home/newfile"]
    user: "1000:1000"
</syntaxhighlight>


Wenn Sie im Zusammenspiel mit Docker und Linux vermeiden möchten, dass neue
Das obige Listing setzt voraus, dass Ihre UID und GID jeweils 1000 ist
Dateien root gehören, können Sie compose.yaml um das Schlüsselwort user erweitern
* Das trifft für den ersten angelegten Benutzer zu
und dort eine UID (User Identification Number) oder GID (Group Identification Num-
* Allgemeingültiger ist die folgende Variante, die aber voraussetzt, dass Sie die Variable UID_GID vor dem Aufruf von docker compose initialisieren:
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
<syntaxhighlight lang="yaml" highlight="" line>
Dockerfile festgelegt werden.
# in compose.yaml
...
    user: ${ UID_GID }
</syntaxhighlight>


# Datei compose . yaml
Sie müssen nun docker compose wie folgt aufrufen
services :
<syntaxhighlight lang="bash" highlight="1" copy>
secrette s t :
UID_GID =" $ ( id -u ): $( id -g) " docker compose up
image : alpine
</syntaxhighlight>
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
=== Benannte Volumes ===
den ersten angelegten Benutzer zu. Allgemeingültiger ist die folgende Variante, die
Volume-Verzeichnis den gewünschten Namen voranstellen
aber voraussetzt, dass Sie die Variable UID_GID vor dem Aufruf von docker compose
* Das Volume muss nochmals in der Top-Level-Ebene volumes angeben werden
initialisieren:
* Dort können Sie gegebenenfalls besondere Eigenschaften des Volumes festlegen


# in compose . yaml
<syntaxhighlight lang="yaml" highlight="" line>
...
# Datei compose.yaml im Verzeichnis test2
user : $ { UID_GID }
services:
  nginx:
    volumes:
      - webdata:/var/www/html/
...


Sie müssen nun docker compose wie folgt aufrufen:
volumes:
  UID_GID =" $ ( id -u ) : $( id -g) " docker compose up
  webdata:
</syntaxhighlight>


Leider ist die Vorgehensweise mit user inkompatibel mit podman-compose. Das Script
; Docker richtet das Volume ein
verarbeitet das Schlüsselwort user zwar prinzipiell korrekt, allerdings tritt nun bei der
Der Volume-Name setzt sich aus dem aktuellen Verzeichnisnamen, dem in der Datei compose.yaml angegebenen Namen sowie ''data_'' zusammen
Ausführung des Containers der Fehler permission denied auf.


=== Benannte Volumes ===
Sofern Sie Docker mit root-Rechten ausführen und das aktuelle Verzeichnis test2 lautet, ergibt sich der folgende Pfad:
Zur Definition benannter Volumes stellen Sie dem Volume-Verzeichnis einfach den
<syntaxhighlight lang="yaml" highlight="" line>
gewünschten Namen (im folgenden Beispiel webdata) voran. Allerdings müssen Sie
/var/lib/docker/volumes/test2_webdata/_data
das Volume ein zweites Mail in der Top-Level-Ebene volumes angeben. Dort können
</syntaxhighlight>
Sie gegebenenfalls besondere Eigenschaften des Volumes festlegen:


# Datei compose . yaml im Verzeichn i s test2
== Volumes für Services ==
services :
Mit [[Docker-Schwarm]] entscheidet der [[Schwarm-Manager]], auf welchem Knoten ein Service ausgeführt wird
nginx :
* Der Ort kann sich also jederzeit ändern!
volumes :
* Bei der Verwendung von Volumes führt das zu Problemen
- webdata :/var/www/html/
* Ein beim ersten Ablauf auf Knoten A eingerichtetes Volume existiert nicht auf Knoten B, wo der Service vielleicht beim nächsten Mal läuft
...
volumes :
webdata :


Docker kümmert sich darum, das Volume einzurichten. Der Volume-Name setzt sich
; Problem umgehen
aus dem aktuellen Verzeichnisnamen, dem in der Datei compose.yaml angegebenen
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.
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
== 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


Volumes für Services
<syntaxhighlight lang="yaml" highlight="" line>
In einem Docker-Schwarm entscheidet der Schwarm-Manager, auf welchem Knoten
environment:
ein Service ausgeführt wird. Der Ort kann sich also jederzeit ändern. Bei der Ver-
  WORDPRESS_DB_HOST: mariadb
wendung von Volumes führt das zu Problemen: Ein beim ersten Ablauf auf Knoten
  WORDPRESS_DB_NAME: wordpress01
A eingerichtetes Volume existiert ja nicht auf Knoten B, wo der Service vielleicht
</syntaxhighlight>
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 ===
<syntaxhighlight lang="yaml" highlight="" line>
Dem Schlüsselwort environment folgen wahlweise Key-Value-Paare oder Listenele-
environment:
mente in der Form var=wert. Die so definierten Umgebungsvariablen gelten bei der
  - WORDPRESS_DB_HOST=mariadb
Ausführung des Kommandos im Container. Die beiden folgenden Listings sind gleich-
  - WORDPRESS_DB_NAME=wordpress01
wertig:
</syntaxhighlight>


environme n t :
; Viele Umgebungsvariablen
WORDPRES S _ D B_ H O S T : mariadb
Mit ''env_file:dateiname'' aus einer Datei lesen
WORDPRES S _ D B_ N A M E : dockerbu c h


environme n t :
== Kommandoausführung ==
- WORDPRES S _D B _ H OS T = mariadb
Normalerweise wird in Containern oder Services das Kommando ausgeführt, das im Image durch ENTRYPOINT und/oder CMD vorgegeben ist
- WORDPRES S _D B _ N AM E = dockerbu ch


Wenn Sie viele Umgebungsvariablen setzen müssen, können Sie die Einstellungen
Siehe auch
mit env_file: dateiname auch aus einer Datei lesen.
* [[dockerfile/Syntax#Container-Startkommando]]


=== Kommandoausführung ===
Bei einem Apache-Image wird das ein Startkommando für den Webserver sein, bei einem MySQL-Image der Dienst des MySQL-Servers etc.
Normalerweise wird in Containern bzw. Services das Kommando ausgeführt, das im
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
dieses mit den Schlüsselwörtern entrypoint und/oder command an. Beachten Sie, dass
* Kommandos, die aus mehreren Teilen zusammengesetzt sind, entweder als Liste oder in der Form <code>["teil1", "teil2", "teil3"]</code> übergeben  
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 "]
<syntaxhighlight lang="yaml" highlight="" line>
command :    ["/bin/bash "]
entrypoint: ["some-script.sh"]
command:    ["/bin/bash"]
</syntaxhighlight>


# mehrteil i g e s Kommando
; Mehrteilige Kommandos
command : [" php " , " -a "]
<syntaxhighlight lang="yaml" highlight="" line>
command: ["php", "-a"]
</syntaxhighlight>
oder
<syntaxhighlight lang="yaml" highlight="" line>
command:
  - "php"
  - "-a"
</syntaxhighlight>


# gleichwe r t i g
== Restart ==
command :
; Restart-Verhalten
- " php "
Mit [[docker compose]] kann mit dem Schlüsselwort ''restart'' das Neustart-Verhalten festgelegt werden
- " -a "
* ob 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''


=== Restart-Verhalten (Docker-spezifisch) ===
; docker stack deploy
Bei Containern, die mit docker compose erzeugt werden, können Sie mit dem Schlüs-
Das restart-Schlüsselwort wird von docker stack deploy ignoriert
selwort restart einstellen, ob sie bei einem Rechnerneustart oder nach einem Fehler
* Für Stack-Services gilt standardmäßig, dass sie bei Bedarf automatisch neu gestartet werden
automatisch neu gestartet werden sollen. Das Defaultverhalten lautet no. Die anderen
* Davon abweichende Einstellungen können Sie mit [[#Deploy-Einstellungen]] festlegen
zulässigen Einstellungen lauten always, on-failure und unless-stopped . (Eine genaue
** deploy.restart_policy
Erläuterung der Schlüsselwörter finden Sie in Abschnitt 6.6, »Container automatisch
starten«.)


restart : always
<syntaxhighlight lang="yaml" highlight="" line>
restart: always
</syntaxhighlight>


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


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


deploy.mode gibt an, wie der Service ausgeführt wird. Die Defaulteinstellung lautet
; docker compose
replicated . Damit kann angegeben werden, wie viele Instanzen ausgeführt werden.
* ignoriert das deploy-Schlüsselwort und alle von ihm abgeleiteten Einstellungen!
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
; Schlüsselwörter
exakt eine Instanz des Service ausgeführt werden soll.
{| class="table table-striped table-hover sortable col1bold col1nowrap"
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
! Wert !! Beschreibung
mögliche Regeln:
|-
| 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.


  - node . id == <xxxx >
Die alternative Einstellung global bestimmt, dass auf jedem Knoten im Schwarm exakt eine Instanz des Service ausgeführt werden soll.
  - node . hostname == <name >
|-
  - node . role == manager | worker
| 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 (Standard: 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 || imitiert die Anzahl der Neustarts. (Standardmäßig gibt es kein Limit.)
|}


deploy.replicas gibt an, wie viele Instanzen des Service gleichzeitig laufen sollen
; compose.yaml
(normalerweise nur eine Instanz).
Einstellungen durch Einrückungen formulieren
deploy.resources.limits.cpus limitiert die CPU-Nutzung des Service. Die Einstel-
lung 0.25 bedeutet, dass der Service ein CPU-Core durchschnittlich zu 25 % auslas-
ten 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. (Standard-
mäßig gibt es kein Limit.)


In compose.yaml müssen die Einstellungen wie üblich durch Einrückungen formuliert
<syntaxhighlight lang="yaml" highlight="" line>
werden:
services:
  nginx:
    image: nginx:alpine
    deploy:
      placement:
        constraints:
          -node.hostname == "dockerhost7"
      replicas: 5
      resources:
        limits:
          cpus: '0.25'
          memory: 50 M
        restart_policy:
          condition: on-failure
          delay: 2 s
</syntaxhighlight>


services :
[[Kategorie:Docker/Compose]]
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

Aktuelle Version vom 19. November 2026, 03:08 Uhr

Docker/Compose/03 compose.yaml - Schlüsselwörter für die Datei compose.yaml von docker compose

Beschreibung

compose.yaml
  • Beginnt in der Regel mit dem Bezeichner services
  • auf den eingerückt frei wählbare Namen mehrerer Dienste folgen
  • Eigenschaften eines Dienstes
    • Nochmals eingerückt, durch Schlüsselwörter festgelegt
Schema
# Grundsätzlicher Aufbau von compose.yaml
services:
  dienstname1:
    schlüsselwort1: einstellung1
    schlüsselwort2: einstellung2
    ...

  dienstname2:
    schlüsselwort1: einstellung1
    schlüsselwort2: einstellung2
    ...
Top-Level-Abschnitte

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
Dokumentation
Vollständige Referenz
Compose Version 2 Spezifikation

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: verzeichnis
docker compose

berücksichtigt 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 und docker stack deploy richtet für die auszuführenden Container oder Services automatisch ein eigenes Netzwerk ein

Zusätzliche Netzwerk

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
Beispiel

Ein Dienst web kann mit dem Netzwerk myownnet kommunizieren

  • Dabei handelt es sich um das in Docker immer verfügbare Host-Netzwerk

Siehe auch

docker network ls
services:
  web:
  ...
  networks:
    - myownnet

# Top-Level-Abschnitt zur Definition zusätzlicher Netzwerke
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)

Folgendes macht die Ports 80 und 443 des Docker-Containers oder -Service auf den Ports 8080 und 8443 des Docker-Hosts zugänglich

ports:
  - "8080:80"
  - "8443:443"

Wenn Sie einen Port nur innerhalb desjenigen Netzwerks freigeben möchten, das docker compose oder docker stack deploy für die Container oder 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

Fedora und RHEL
Hier müssen Sie für Volumes, die nicht innerhalb des Standardverzeichnisses für Docker oder 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

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

Benuter/Gruppen in Volumes

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 oder 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.
Beispiel

Folgende Datei 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:
  secrettest: 
    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
<syntaxhighlight lang="bash" highlight="">
-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
Zusammenspiel Docker und Linux

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:
  secrettest: 
    image: alpine
    volumes: 
      - ./:/home:z
    command: ["touch","/home/newfile"]
    user: "1000:1000"

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

Benannte Volumes

Volume-Verzeichnis den gewünschten Namen voranstellen

  • Das Volume muss nochmals in der Top-Level-Ebene volumes angeben werden
  • Dort können Sie gegebenenfalls besondere Eigenschaften des Volumes festlegen
# Datei compose.yaml im Verzeichnis test2
services:
  nginx:
    volumes:
      - webdata:/var/www/html/
...

volumes:
 webdata:
Docker richtet das Volume ein

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_webdata/_data

Volumes für Services

Mit 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 nicht auf Knoten B, wo der Service vielleicht beim nächsten Mal läuft
Problem umgehen

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
environment:
  WORDPRESS_DB_HOST: mariadb
  WORDPRESS_DB_NAME: wordpress01
environment:
  - WORDPRESS_DB_HOST=mariadb
  - WORDPRESS_DB_NAME=wordpress01
Viele Umgebungsvariablen

Mit env_file:dateiname aus einer Datei lesen

Kommandoausführung

Normalerweise wird in Containern oder Services das Kommando ausgeführt, das im Image durch ENTRYPOINT und/oder CMD vorgegeben ist

Siehe auch

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

  • Kommandos, die aus mehreren Teilen zusammengesetzt sind, entweder als Liste oder in der Form ["teil1", "teil2", "teil3"] übergeben
entrypoint:  ["some-script.sh"]
command:     ["/bin/bash"]
Mehrteilige Kommandos
command: ["php", "-a"]

oder

command:
  - "php"
  - "-a"

Restart

Restart-Verhalten

Mit docker compose kann mit dem Schlüsselwort restart das Neustart-Verhalten festgelegt werden

  • ob 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
docker stack deploy

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-Einstellungen festlegen
    • deploy.restart_policy
restart: always

Siehe auch

Deploy

Deploy-Einstellungen

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!
Schlüsselwörter
Wert Beschreibung
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
on-failure|none gibt an, unter welchen Umständen ein Service automatisch neu gestartet werden soll (Standard: 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 imitiert die Anzahl der Neustarts. (Standardmäßig gibt es kein Limit.)
compose.yaml

Einstellungen durch Einrückungen formulieren

services:
  nginx:
    image: nginx:alpine
    deploy:
      placement:
        constraints:
          -node.hostname == "dockerhost7"
      replicas: 5
      resources:
        limits:
          cpus: '0.25'
          memory: 50 M
        restart_policy:
          condition: on-failure
          delay: 2 s