Docker/Image/Definition/02 Dockerfile-Syntax

Aus Foxwiki
Version vom 19. November 2026, 07:55 Uhr von Dirkwagner (Diskussion | Beiträge) (Dirkwagner verschob die Seite Docker/Image/Eigene Images/02 Dockerfile-Syntax nach Docker/Image/Definition/02 Dockerfile-Syntax: Textersetzung - „Docker/Image/Eigene Images“ durch „Docker/Image/Definition“)
Wechseln zu:Navigation, Suche

Schlüsselwörter

Überblick

Wichtige Dockerfile-Schlüsselwörter

Wert Beschreibung
Schlüsselwort Beschreibung
ADD Kopiert Dateien in das Dateisystem des Images
CMD Führt das angegebene Kommando beim Container-Start aus
COPY Kopiert Dateien aus dem Projektverzeichnis in das Image
ENTRYPOINT Führt das angegebene Kommando immer beim Container-Start aus
ENV Setzt eine Umgebungsvariable
EXPOSE Gibt die aktiven Ports des Containers an
FROM Gibt das Basis-Image an
LABEL Legt eine Zeichenkette fest
RUN Führt das angegebene Kommando aus
USER Gibt den Account für RUN, CMD und ENTRYPOINT an
VOLUME Gibt Volume-Verzeichnisse an
WORKDIR Legt das Defaultverzeichnis für den Container fest

FROM

Das Ausgangs-Image festlegen (FROM)

Eigene Images werden oft von anderen Images abgeleitet

  • Den Namen des Ausgangs- Image geben Sie mit FROM an
  • Nach Möglichkeit sollten Sie dabei offizielle, gut gewartete Images verwenden

ADD

Dateien hinzufügen (ADD versus COPY)

Die Kommandos ADD und COPY scheinen auf den ersten Blick dieselbe Aufgabe zu erfüllen: Sie kopieren Dateien in das Dateisystem des zu erstellenden Images

  • ADD ist dabei das flexiblere Kommando, das sich vom simplen COPY in drei Punkten abhebt:
  • ADD akzeptiert als Quellparameter nicht nur eine lokale Datei, sondern auch eine URL
  • Damit können Dateien aus dem Internet heruntergeladen und in das Image-Dateisystem kopiert werden
  • Wenn der Quellparameter von ADD ein Verzeichnis ist, wird der gesamte Inhalt dieses Verzeichnisses in das Image kopiert
  • Wenn die Quelldatei bei ADD ein lokales TAR-Archiv ist, wird es automatisch ausgepackt
  • Das funktioniert auch für Archive, die mit den Verfahren gzip, bzip2 oder xz komprimiert sind

Die Dockerfile-Dokumentation empfiehlt, ADD nur dann einzusetzen, wenn eine dieser Zusatzfunktionen genutzt wird

  • Für das simple Kopieren einer lokalen Datei ist COPY zu bevorzugen

Sowohl bei ADD als auch bei COPY können Sie mit --chown=user:group angeben, welchem Account und welcher Gruppe die Datei im Image-Dateisystem zugeordnet werden soll

.dockerignore

Oft werden mit ADD oder COPY ganze Verzeichnisse in einen Container kopiert

  • Dabei ist es oft zweckmäßig, Backup-Dateien, temporäre Dateien etc. auszuschließen
  • Das gelingt ganz einfach, wenn Sie in dem Verzeichnis die Datei .dockerignore einrichten
  • Sie enthält Muster von Dateien, die nicht berücksichtigt werden sollen
  • Die Syntax entspricht der von .gitignore und ist leicht zu verstehen
Beispiel
  • Alle Dateien ausschließen, die mit ~ enden
  • Das Verzeichnis tmp ausschließen
*~
tmp/*

Container-Startkommando

Container-Startkommando (CMD und ENTRYPOINT)

Welches Programm wird ausgeführt, wenn ein Container mit run erstmalig oder später mit start ausgeführt wird? Auf diese Frage gibt es verwirrend viele Antworten:

  • Sie können im Dockerfile mit den Schlüsselwörtern CMD und/oder ENTRYPOINT ein Defaultkommando angeben
  • Beim Einrichten des Containers können Sie bei der CMD-Variante ein alternatives Kommando angeben oder bei der ENTRYPOINT‑Variante dieses um weitere Parameter ergänzen
  • Gegebenenfalls können Sie auch das ENTRYPOINT‑Kommando durch ein eigenes Kommando ersetzen, wenn Sie dieses mit der Option --entrypoint an docker run übergeben
  • Während ein Container läuft, können Sie mit docker exec ein beliebiges weiteres Kommando ausführen

Die empfohlene Syntax für ENTRYPOINT oder CMD sieht so aus, dass Sie den vollständigen Dateinamen des Kommandos sowie seine Parameter jeweils in doppelte Anführungszeichen stellen und durch Kommata getrennt in eckigen Klammern übergeben:

CMD    ["/bin/ls", "/var"]

CMD und ENTRYPOINT scheinen dieselbe Aufgabe zu erfüllen

  • Es gibt aber einen entscheidenden Unterschied:
  • CMD: Das Kommando, das Sie an docker run nach dem Image-Namen übergeben, wird anstelle von CMD ausgeführt
  • ENTRYPOINT : Die an docker run übergebenen Parameter werden dem ENTRYPOINT hinzugefügt

Eine mehrfache Angabe von CMD oder ENTRYPOINT ist nicht vorgesehen

  • Passiert dies doch, gilt die letzte derartige Anweisung

In der Praxis ist bei vielen Basis-Images der ENTRYPOINT nicht definiert, also leer

  • CMD enthält den Namen einer Shell, also/bin/sh oder/bin/bash
  • Auch bei Images für Programmiersprachen ist ENTRYPOINT zumeist undefiniert, CMD startet entweder eine Shell der Programmiersprache oder ist auch leer

ENTRYPOINT- und CMD-Einstellungen

ENTRYPOINT- und CMD-Einstellungen bei einigen populären Images
Image ENTRYPOINT CMD
Alpine Linux ["/bin/sh"]
Apache ["httpd-foreground"]
Debian ["/bin/bash"]
Nginx ["nginx", "-g", "daemon off;"]
MySQL/MariaDB ["docker-entrypoint.sh"] ["mysqld"]
Nextcloud ["entrypoint.sh"] ["apache2-foreground"]
Node.js ["node"]
OpenJDK (Java) ["jshell"]
PHP ["docker-php-entrypoint"] ["php", "-a"]
Python ["python3"]
Ubuntu ["/bin/bash"]
WordPress ["docker-entrypoint.sh"] ["apache2-foreground"]

Folgende Tabelle zeigt, wie sich aus unterschiedlichen Angaben für ENTRYPOINT, CMD und dem Parameter von docker run das auszuführende Kommando ergibt:

  • Beachten Sie, dass das Schlüsselwort RUN nichts mit CMD und ENTRYPOINT zu tun hat! RUN gibt Kommandos an, die einmalig beim Erzeugen des Images ausgeführt werden sollen.
  • CMD oder ENTRYPOINT geben dagegen das Kommando an, das später beim Start des Containers auszuführen ist.
Zusammensetzung des Kommandos, das durch docker run ausgeführt wird
ENTRYPOINT CMD run-Parameter ausgeführt wird
["script.sh"] script.sh
["script.sh"] /bin/bash script.sh /bin/bash
["script.sh"] ["mysqld"] script.sh mysqld
["script.sh"] ["mysqld"] /bin/bash script.sh /bin/bash
["/bin/sh"] /bin/sh
["/bin/sh"] /bin/bash /bin/bash

Bei Images für Serverdienste verweist ENTRYPOINT dagegen oft auf ein Shell-Script, das sich zuerst um diverse Initialisierungsarbeiten kümmert (siehe Tabelle 4.2):

  • Sind diese erledigt, wird das mit CMD angegebene Kommando ausgeführt, in der Regel also der Serverdienst gestartet.
  • Wenn keine Initialisierungsarbeiten erforderlich sind, ist ENTRYPOINT leer.
Shell-Variante zu CMD und ENTRYPOINT

Die Docker-Dokumentation empfiehlt, das auszuführende Kommando und seine Parameter wie in den obigen Beispielen in eckigen Klammern und in doppelten Anführungszeichen an CMD oder ENTRYPOINT zu übergeben.

  • Es gibt aber eine zweite Syntaxform, gemäß der Sie das Kommando einfach ohne Klammern und Anführungszeichen weitergeben, also z. B. als CMD ls /etc/*.
  • Das Kommando wird dann über eine Shell ausgeführt.
  • In diesem Fall erhält nicht das Kommando die Prozess-ID 1, sondern die Shell.

Die Shell-Variante hat Vor- und Nachteile:

  • Zu den Vorteilen zählt der Umstand, dass die von der Shell bekannten Substitutionsmechanismen funktionieren.
  • Beispielsweise wird * durch Dateinamen ersetzt oder $VAR durch den Inhalt der Umgebungsvariablen.
  • Außerdem können Sie darauf verzichten, den vollständigen Pfad des Kommandos anzugeben – die Shell findet das Kommando, sofern es sich in einem der PATH-Verzeichnisse befindet.

Der größte Nachteil besteht darin, dass es keine Signalweiterleitung gibt: (Strg)+(C) bei einem interaktiven Container oder docker stop bei einem nicht interaktiven Container stoppt zwar die Shell, gibt dem eigentlich auszuführenden Kommando aber keine Gelegenheit, die Signalverarbeitung selbst durchzuführen.

Arbeitsverzeichnis festlegen (WORKDIR)

WORKDIR legt fest, welches Verzeichnis beim Ausführen des Containers als aktives Verzeichnis gilt:

  • Zugleich gilt das mit WORKDIR angegebene Verzeichnis auch für andere Schlüsselwörter wie RUN oder COPY als Defaultverzeichnis, wenn nicht ein anderes Zielverzeichnis mit einem absoluten Pfad angegeben wird.
Kommandos ausführen (RUN)

Die mit RUN angegebenen Kommandos werden bei der Erzeugung des Images ausgeführt:

  • Häufig handelt es sich dabei um Kommandos zur Installation von Paketen.
  • Da der Prozess automatisiert abläuft, müssen Sie interaktive Rückfragen vermeiden.
  • Bei vielen Paketverwaltungskommandos reicht dazu die Option -y aus (yes, also alle Rückfragen bejahen).
RUN apt-get update -y && \
apt-get install -y --no-install-recommends \
subversion \
joe \
vim \
less && \
apt-get clean && \
rm -rf /var/lib/apt/lists/*
Tipp

Jedes RUN-Kommando fügt Ihrem Image einen weiteren Layer hinzu, also eine Dateisystemebene. (Wie Images aus mehreren übereinandergelegten Dateisystemen zusammengesetzt werden, beschreiben wir in Abschnitt 6.7, Docker-Interna.) Eine große Anzahl von Layern macht Images aber ineffizient:

  • Deswegen ist es empfehlenswert, wie im obigen Beispiel möglichst viele Anweisungen in einem RUN-Kommando zu kombinieren.

Damit Images nicht größer als notwendig werden, sollten außerdem alle Cache-Dateien unmittelbar gelöscht werden (hier mit apt-get clean und rm):

  • Wenn diese Dateien in einem Layer landen, blähen sie das Image unnötig auf.
Volume-Verzeichnisse (VOLUME)

VOLUME gibt an, welche Verzeichnisse als Volumes im Dateisystem des Hosts abgebildet werden sollen:

  • Wie bei CMD geben Sie mehrere Verzeichnisse in eckigen Klammern und jeweils in doppelten Anführungszeichen an:
VOLUME ["/var/lib/mysql", "/var/log/mysql"]

Wo die Volumes tatsächlich im Host-Dateisystem landen, hängt davon ab, wie der Container eingerichtet wird:

  • Wenn Sie docker run oder docker create ohne die Option -v ausführen, richtet Docker für jedes Volume ein Verzeichnis mit einer zufälligen UID ein (/var/lib/docker/volumes/uid).
  • Der Anwender des Images kann mit der Option -v den gewünschten Ort im Host auch selbst angeben:
docker run ... -v /myvolumes/mysql:/var/lib/mysql \
-v /myvolumes/log:/var/log/mysql imagename

Fedora- und RHEL-Anwender müssen beachten, dass SELinux normalerweise keine Volumes außerhalb von /var/lib/docker erlaubt:

  • Abhilfe schafft in solchen Fällen das zusätzliche Flag :z, das Sie der Volume-Option hinzufügen (etwa -v /myvolumes/mysql/:/var/lib/mysql:z).

Dockerfile-Syntax

Die Datei Dockerfile legt die Eigenschaften eigener Images fest

Folgende Tabelle erläutert die wichtigsten Schlüsselwörter

Weiterer Informationen

Beispiele

Einfache Methode

Mit Dockerfile-Syntax vertraut werden

  • Im Docker Hub Dockerfiles von Images untersuchen, die ähnliche Aufgaben erfüllen wie Ihr eigenes Image