
TL;DR
|
Ein Dockerfile ist eine reine Textdatei, die Schritt-für-Schritt-Anweisungen zum Erstellen eines Container-Images enthält. Stell dir das wie ein Rezept vor: Es listet auf, womit man anfängt, was hinzugefügt wird und wie das Ergebnis ausgeführt wird, sodass jeder genau dasselbe App-Paket erstellen kann.
Wenn du ein Projekt geöffnet hast und eine Datei gefunden hast, die einfach Dockerfile, ohne Dateiendung, erklärt dir dieser Leitfaden, wie du sie lesen kannst. Er behandelt, wie Dockerfiles, Images und Container zusammenpassen, führt dich durch ein konkretes Beispiel und erklärt, wann du eines schreiben musst.
Das Wichtigste auf einen Blick: Ein Dockerfile ist das Rezept, ein Image ist das Ergebnis des Rezepts und ein Container ist das ausgeführte Image.
Diese drei Begriffe tauchen immer zusammen auf und lassen sich leicht verwechseln.
| Begriff | Was es ist | Vergleich in der Küche |
|---|---|---|
| Dockerfile | Eine Textdatei mit Anweisungen | Das Rezept |
| Image | Ein gepackter, schreibgeschützter Snapshot einer App und allem, was sie benötigt: Code, Bibliotheken und Systemtools | Eine Reihe von Mahlzeiten, zubereitet und tiefgefroren |
| Container | Eine laufende Kopie eines Images | Eine Mahlzeit, aufgewärmt und serviert |
Du erstellst einmal ein Dockerfile, um ein Image zu erhalten, und kannst dieses Image in so vielen Containern ausführen, wie du brauchst. Jeder Container, der aus demselben Image stammt, ist zunächst identisch – und genau darum geht es: Die App verhält sich auf dem Laptop eines Entwicklers, in einer Testpipeline und auf einem Server immer gleich.
Images lassen sich zudem teilen. Teams veröffentlichen sie in Registern wie Docker Hub, sodass andere sie herunterladen und ausführen können, ohne selbst etwas erstellen zu müssen. Viele Dockerfiles basieren auf einem dieser veröffentlichten Images, anstatt ganz von vorne anzufangen.
Das Wichtigste auf einen Blick: Viele Dockerfiles folgen dem gleichen Aufbau: Sie gehen von einem Basis-Image aus, fügen die Abhängigkeiten und das Programm der App hinzu und legen dann fest, wie sie gestartet werden soll.
Hier ist ein Dockerfile für eine kleine Node.js-Web-App:
FROM node:24-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]| Zeile | Was es bewirkt |
|---|---|
FROM node:24-slim | Ausgangspunkt ist ein veröffentlichtes Image, auf dem Node.js 24 bereits installiert ist. slim ist eine kleinere Variante mit weniger zusätzlichen Tools |
WORKDIR /app | Verwende den /app Ordner im Image für alles, was folgt |
COPY package.json package-lock.json ./ | Kopiere nur die Dateien, in denen die Abhängigkeiten der App aufgeführt sind |
RUN npm ci --omit=dev | Installiere genau die Versionen der Abhängigkeiten aus der Lock-Datei und lass dabei Tools weg, die nur während der Entwicklung benötigt werden |
COPY . . | Kopiere den restlichen Code der App in das Image |
EXPOSE 3000 | Beachte, dass die App auf Port 3000 lauscht. Hier wird der Port dokumentiert, und der Port muss weiterhin veröffentlicht werden, wenn der Container läuft |
CMD ["node", "server.js"] | Der Befehl, der die App startet, wenn ein Container läuft |
Das separate Kopieren der Abhängigkeitsdateien vor dem restlichen Code ist beabsichtigt. Docker erstellt ein Image in Schichten, eine pro Anweisung, und verwendet jede Schicht wieder, deren Eingaben sich nicht geändert haben. Das Kopieren der Abhängigkeitsdateien zuerst bedeutet, dass eine Änderung am Code der App keine vollständige Neuinstallation aller Abhängigkeiten auslöst, sodass Neuaufbauten viel schneller erfolgen. Unser Leitfaden Was ist eine Lock-Datei? erklärt, warum diese Lock-Datei wichtig ist.
Das gleiche Prinzip funktioniert auch in anderen Sprachen. Ein Python-Dockerfile könnte beispielsweise FROM python:3.13-slim und installiert anhand einer Requirements- oder Lock-Datei, während ein PHP-Dockerfile vielleicht von einem offiziellen php Image und führt Composer aus.
Das Wichtigste auf einen Blick: Etwa ein Dutzend Anweisungen decken die Dockerfiles ab, die du wahrscheinlich lesen wirst. Jede davon besteht aus einem einzelnen Wort in Großbuchstaben am Anfang einer Zeile.
| Anweisung | Was sie bewirkt |
|---|---|
FROM | Legt das Start-Image fest. Jedes Dockerfile beginnt damit |
WORKDIR | Legt den Ordner innerhalb des Images fest, in dem spätere Anweisungen ausgeführt werden |
COPY | Kopiert Dateien aus deinem Projekt in das Image |
ADD | Zum Beispiel COPY, kann aber auch Archive entpacken und von Webadressen herunterladen. Verwende COPY nur, wenn du diese Zusatzfunktionen brauchst |
RUN | Führt während der Erstellung des Images einen Befehl aus, z. B. die Installation von Paketen |
ENV | Legt eine Umgebungsvariable innerhalb des Images fest |
ARG | Legt einen Wert fest, der nur während der Erstellung des Images verfügbar ist |
EXPOSE | Dokumentiert, auf welchem Port die App lauscht |
USER | Wechselt für die folgenden Anweisungen und Befehle zu einem anderen Benutzer |
CMD | Legt den Standardbefehl fest, den ein Container beim Start ausführt. Dieser kann beim Starten des Containers überschrieben werden |
ENTRYPOINT | Legt das Hauptprogramm fest, das ein Container immer ausführt. Alles, was CMD wird als zusätzliche Optionen an ihn übergeben |
Der Unterschied zwischen RUN und CMD verwirrt viele Leute. RUN findet einmalig statt, während das Image erstellt wird. CMD findet jedes Mal statt, wenn ein Container aus diesem Image gestartet wird.
Das Wichtigste zum Merken: docker build wandelt ein Dockerfile in ein Image um, und docker run startet daraus einen Container.
Führe diese Befehle in dem Ordner aus, der das Dockerfile enthält:
| Befehl | Was es bewirkt |
|---|---|
docker build -t myapp . | Erstellt ein Image aus dem Dockerfile in diesem Ordner und benennt es „myapp“. Der Punkt bedeutet „dieser Ordner“ |
docker run -p 3000:3000 myapp | Starte einen Container aus dem Image und mache Port 3000 unter localhost:3000 erreichbar |
docker run -d -p 3000:3000 myapp | Das Gleiche, aber im Hintergrund |
docker images | Liste die Images auf deinem Computer auf |
docker ps | Liste die laufenden Container auf |
docker stop <container> | Beende einen laufenden Container |
docker push <name> | Lade ein Image in eine Registry hoch, damit andere es nutzen können |
Wenn eine App neben sich noch andere Dienste benötigt, wie zum Beispiel eine Datenbank, wird es docker run mühsam. Genau dafür gibt es Docker Compose. Unser Leitfaden So verwendest du .env-Dateien mit Docker Compose zeigt, wie man mehrere Container gemeinsam startet.
Das Wichtigste auf einen Blick: Die schwerwiegendsten Fehler in Dockerfiles bestehen darin, dass Geheimnisse in Images gespeichert werden oder diese dadurch langsam und aufgebläht werden. Ein paar gute Gewohnheiten helfen, das zu verhindern.
Eine Zeile wie COPY . . kopiert alles im Ordner, einschließlich einer .env Datei voller Passwörter – es sei denn, du gibst Docker eine andere Anweisung. Jeder, der das Image erhält, kann diese Dateien lesen. Füge eine .dockerignore Datei neben dem Dockerfile. Sie funktioniert wie eine .gitignore-Datei und hält Dateien aus dem Image fern:
.env
.git
node_modulesDas Gleiche gilt für Passwörter, die mit ENV oder ARG im Dockerfile festgelegt wurden: Sie bleiben im Image lesbar. Übergebe Geheimnisse stattdessen bei der Ausführung des Containers. Unsere Anleitungen Was ist eine .gitignore-Datei? und Was sind Umgebungsvariablen? behandeln beide Aspekte.
Das Kopieren des gesamten Codes vor der Installation der Abhängigkeiten bedeutet, dass bei jeder kleinen Codeänderung alles neu installiert wird. Kopiere zuerst die Abhängigkeitsdateien und installiere sie, dann kopiere den Rest, wie im obigen Beispiel.
Wenn du von einem vollständigen Basis-Image ausgehst, werden Tools mitgeladen, die die App nie nutzt – das verlangsamt den Download der Images und bietet Angreifern mehr Angriffsfläche. Verwende eine schlanke Variante, sofern vorhanden. Für Apps, die Build-Tools nur während der Kompilierung benötigen, nutzt ein Multi-Stage-Build ein Image zum Erstellen der App und kopiert nur das Ergebnis in ein zweites, kleineres Image.
FROM node:latest oder FROM node wählt die jeweils aktuellste Version am Tag des Builds aus, sodass dasselbe Dockerfile im Abstand von einem Monat unterschiedliche Images erzeugen kann. Fixiere eine Version, zum Beispiel node:24-slim.
Standardmäßig laufen Container als Root-Benutzer, der volle Kontrolle innerhalb des Containers hat. Viele offizielle Basis-Images enthalten einen normalen Benutzer, und der Wechsel zu diesem mit USER begrenzt den Schaden, falls die App jemals kompromittiert werden sollte.
Eine App, die nur auf 127.0.0.1 oder localhost innerhalb eines Containers lauscht, ist von deinem Browser aus nicht erreichbar, selbst wenn der Port veröffentlicht ist. Konfiguriere sie so, dass sie auf 0.0.0.0, was bedeutet: „Verbindungen von überall akzeptieren“.
Das Wichtigste auf einen Blick: Erstelle ein Dockerfile, wenn du deine eigene App als Container verpackst. Einige Hosting-Plattformen, darunter Upsun Cloud, erstellen den Container stattdessen anhand einer Konfigurationsdatei für dich.
Du benötigst ein Dockerfile, wenn:
Du brauchst möglicherweise kein Dockerfile, wenn deine Hosting-Plattform die App für dich erstellt. Anstatt die Build-Schritte selbst zu schreiben, beschreibst du, was die App benötigt – zum Beispiel die Sprachversion und wie sie gestartet wird –, und die Plattform erstellt den Container.
Upsun Cloud erstellt deine App aus der cloud .upsun/config.yaml, sodass du kein Dockerfile dafür schreiben musst. Es gibt drei Möglichkeiten, eine App zu beschreiben:
| App-Typ | Was du beschreibst | Geeignet für |
|---|---|---|
| Image mit einer einzigen Laufzeitumgebung | Eine Sprache und Version, zum Beispiel nodejs:26, plus Befehle zum Erstellen und Starten | Typische Web-Apps |
| Zusammensetzbares Image | Mehrere Laufzeiten und Tools in einem Container, ausgewählt aus über 120.000 Paketen in der Nix-Paketsammlung | Apps, die zusätzliche Systemtools oder mehr als eine Sprache benötigen |
Docker-Image (type: docker:1) | Ein vorgefertigtes öffentliches Image, das Upsun Cloud unverändert ausführt | Selbst gehostete Tools, für die bereits ein offizielles Image verfügbar ist |
Für die Node.js-App aus dem obigen Beispiel sind auf Upsun Cloud nur wenige Zeilen erforderlich:
applications:
app:
type: "nodejs:26"
web:
commands:
start: "node server.js"Bei Node.js-Apps installiert der Standard-Build von Upsun Cloud deine Abhängigkeiten mit npm, sodass die in deiner Dockerfile beschriebenen Schritte ohne diese auskommen.
Die Docker-Image-Option hat einige Einschränkungen, die du kennen solltest. Upsun Cloud erstellt für diesen App-Typ kein Dockerfile aus deinem Repository. Es wird ein Image ausgeführt, das bereits erstellt und veröffentlicht wurde. Build-Hooks werden nicht unterstützt; du bist dafür verantwortlich, das Image zu aktualisieren, wenn der Herausgeber Sicherheitspatches veröffentlicht, und in der Dokumentation werden Meilisearch und n8n als die bisher verifizierten Images aufgeführt.
Du kannst 15 Tage lang kostenlos auf Upsun Cloud bereitstellen, ganz ohne Kreditkarte, oder dir ansehen, wie Git-gesteuerte Automatisierung deine App anhand der Konfiguration erstellt.
Ein Dockerfile ist eine Textdatei mit Anweisungen. Ein Image ist das Ergebnis, das du erhältst, wenn du diese Anweisungen ausführst: ein gepackter, sofort einsatzbereiter Snapshot der App.
Ein Dockerfile beschreibt, wie ein Image erstellt wird. Eine Compose-Datei beschreibt, wie mehrere Container gemeinsam ausgeführt werden, zum Beispiel eine App, eine Datenbank und ein Cache. Eine Compose-Datei nutzt oft ein Dockerfile, um das eigene Image der App zu erstellen.
Nein. Die Datei heißt in der Regel genau Dockerfile, mit einem großen D und ohne Dateiendung. Du kannst einen anderen Namen verwenden und mit docker build -f.
Beide legen fest, was ein Container beim Start ausführt. CMD ist ein Standardwert, der beim Starten des Containers leicht zu ersetzen ist. ENTRYPOINT legt das Hauptprogramm fest, und alles, was in CMD wird als zusätzliche Optionen an ihn übergeben.
Eine Datei, in der aufgelistet ist, was Docker beim Kopieren deines Projekts in ein Image auslassen soll, wie z. B. .env-Dateien, den .git-Ordner und installierte Abhängigkeiten. Sie funktioniert ähnlich wie eine .gitignore-Datei.
Das hängt davon ab, wo du die App bereitstellst. Plattformen, auf denen du deine eigenen Container ausführst, benötigen eine. Plattformen, die deine App anhand einer Konfiguration erstellen, wie zum Beispiel Upsun Cloud, benötigen keine.
