Ein Dockerfile kann eine Anwendung zuverlässig ausliefern – oder bei jedem Build Zeit, Speicher und Vertrauen kosten. Für lokale Experimente reicht oft ein Image, das irgendwie startet. In Production zählt mehr: Der Build muss wiederholbar sein, das Image nur Laufzeit-Code enthalten und ein kompromittierter Prozess möglichst wenig dürfen.

Dieser Leitfaden richtet sich an Einsteiger und konzentriert sich auf die Maßnahmen mit dem größten Effekt. Nicht jede Anwendung braucht jede Optimierung. Ein sauberer Ausgangspunkt braucht aber keine komplizierte Architektur.

Erst verstehen: Was landet im Image?

Ein Dockerfile baut Schicht für Schicht. Jede COPY- und RUN-Anweisung hinterlässt eine Schicht; das finale Image enthält deren Dateisystemzustand. Daraus folgen drei praktische Regeln:

• Alles im Build-Kontext kann versehentlich ins Image geraten.
• Tools aus der Build-Phase bleiben ohne Trennung im Runtime-Image.
• Eine frühe Änderung kann den Cache späterer Schritte ungültig machen.

Das Dockerfile beeinflusst damit Image-Größe, Build-Zeit, Angriffsfläche und die Frage, ob derselbe Commit morgen noch dasselbe Artefakt erzeugt.

Kleine Base Images – aber nicht blind Alpine

Ein vollständiges Ubuntu ist selten nötig. Für viele Anwendungen ist ein schlankes, gepflegtes Basis-Image ein besserer Start:

FROM node:22.18.0-bookworm-slim

slim spart Ballast gegenüber einem vollständigen Distribution-Image und bleibt für viele native Node-Module kompatibler als Alpine. Alpine kann sehr klein sein, verwendet aber musl statt glibc. Das ist kein Problem per se, führt bei manchen nativen Abhängigkeiten aber zu Extraarbeit.

Die Regel lautet daher nicht „immer Alpine“, sondern: Nimm das kleinste Image, das zur Anwendung und ihren Abhängigkeiten passt. Weniger installierte Software bedeutet weniger Code zum Patchen und eine kleinere Angriffsfläche – nicht automatisch null Sicherheitslücken.

Kein latest: Versionen und Digests festlegen

FROM node:latest

latest ist kein Release-Kanal mit Garantien. Der Tag kann morgen auf eine andere Node-Version zeigen. Ein Build, der gestern lief, kann dann ohne Änderung am eigenen Code brechen.

Mindestens die konkrete Version angeben:

FROM node:22.18.0-bookworm-slim

Für vollständig identische Base-Image-Bytes wird zusätzlich ein Digest gepinnt:

FROM node:22.18.0-bookworm-slim@sha256:<digest>

Das ist bewusst strenger: Sicherheitsupdates kommen dann nicht automatisch mit. Deshalb Digests regelmäßig geprüft aktualisieren, statt sie einmal festzuschreiben und zu vergessen.

Multi-Stage Builds: Bauen und Ausführen trennen

Compiler, Testwerkzeuge und Development-Abhängigkeiten braucht ein Server zur Laufzeit nicht. Multi-Stage Builds trennen genau diese Aufgaben.

Ein typisches Problem sieht so aus:

FROM node:22
COPY . .
RUN npm install
RUN npm run build
CMD ["node", "dist/server.js"]

Das finale Image enthält Quellcode, npm-Cache, Build-Umgebung und meist auch Development-Abhängigkeiten. Besser ist eine eigene Laufzeit-Stufe:

FROM node:22.18.0-bookworm-slim AS build
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .
RUN npm run build

FROM node:22.18.0-bookworm-slim AS production-deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev && npm cache clean --force

FROM node:22.18.0-bookworm-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production

RUN groupadd --system --gid 10001 app \
    && useradd --system --uid 10001 --gid app --home-dir /nonexistent app

COPY --from=production-deps --chown=app:app /app/node_modules ./node_modules
COPY --from=build --chown=app:app /app/dist ./dist
COPY --from=build --chown=app:app /app/package.json ./package.json

USER app
EXPOSE 3000
CMD ["node", "dist/server.js"]

Die Build-Stufe darf alles Nötige enthalten. Die Runtime-Stufe erhält nur Build-Ausgabe und Produktions-Abhängigkeiten. Das verkleinert das Artefakt und verhindert, dass versehentlich Compiler oder Tests im Servercontainer landen.

Bei statischen Websites oder kompilierten Go- und Rust-Programmen fällt die Runtime-Stufe oft noch kleiner aus: Es werden nur das erzeugte Binary oder die statischen Dateien kopiert.

Docker-Cache gezielt ausnutzen

Docker kann einen Schritt wiederverwenden, wenn sich die vorherigen Schichten nicht geändert haben. Darum kommen Abhängigkeitsdateien vor dem restlichen Quellcode:

COPY package.json package-lock.json ./
RUN npm ci

COPY . .
RUN npm run build

Eine Änderung an einer README oder einer einzelnen Source-Datei führt so nicht zu einer neuen Paketinstallation. Erst bei Änderungen an package.json oder Lockfile wird npm ci erneut ausgeführt.

Das gleiche Muster gilt für andere Ökosysteme: Cargo.toml und Cargo.lock vor Rust-Quellcode, requirements.txt vor Python-Code. Cache-Optimierung muss lesbar bleiben. Ein komplexer Trick, der nur wenige Sekunden spart, ist selten die Wartung wert.

.dockerignore begrenzt den Build-Kontext

Bevor Docker die erste Zeile verarbeitet, sendet der Client den Build-Kontext an den Builder. Ohne .dockerignore können Git-Historie, lokale Abhängigkeiten, Testartefakte oder eine .env-Datei dort landen.

Für ein Node-Projekt ist das ein brauchbarer Ausgangspunkt:

.git
.github
node_modules
coverage
.env
.env.*
!.env.example
*.log
.vscode
.idea

node_modules gehört fast nie in den Kontext: Es wird im Image für dessen Linux-Architektur installiert. Lokale Module von macOS oder Windows sind dafür ohnehin die falsche Grundlage.

Die Datei ist kein Geheimnisschutz. Ein Secret, das bereits per COPY . . in eine frühere Schicht gelangt ist, bleibt in der Image-Historie. Secrets gehören deshalb nicht in das Projektverzeichnis, das gebaut wird.

COPY statt ADD

Für normale Dateien und Verzeichnisse ist COPY die klare Wahl:

COPY . .

ADD kann zusätzlich lokale Archive automatisch entpacken und URLs laden. Diese Sonderfunktionen machen die Anweisung schwerer vorhersehbar und sind hier nicht nötig.

ADD . .

ADD ist nicht verboten. Es ist passend, wenn das automatische Entpacken eines lokalen Tar-Archivs wirklich beabsichtigt ist. Für den üblichen Quellcode-Kopiervorgang beschreibt COPY die Absicht genauer.

Nicht als Root starten

Container laufen standardmäßig oft als Root. Das macht einen Fehler in der Anwendung nicht automatisch zu einem Host-Angriff, gibt dem Prozess im Container aber mehr Rechte als nötig.

Lege einen dedizierten Benutzer an und wechsle vor dem Start:

RUN groupadd --system --gid 10001 app \
    && useradd --system --uid 10001 --gid app --home-dir /nonexistent app

COPY --chown=app:app ./dist ./dist
USER app

COPY --chown verhindert den häufigen Folgefehler: Der Prozess läuft zwar als unprivilegierter Benutzer, kann seine Dateien oder Log-Verzeichnisse aber nicht lesen beziehungsweise schreiben.

Für Ports unter 1024, Paketinstallationen und manche Build-Schritte sind Root-Rechte nötig. Diese gehören vor USER app, nicht in die Laufzeit der Anwendung.

Secrets weder in ENV noch in Build-Args

Folgendes gehört nicht in ein Dockerfile:

ENV DB_PASSWORD=mein-passwort

Auch ARG DB_PASSWORD=... ist kein sicherer Ersatz. Build-Argumente können in Metadaten, Logs oder Build-Historie sichtbar werden. Ebenso problematisch: COPY . ., wenn eine lokale .env oder ein Schlüssel mitkopiert wird.

Zur Laufzeit kommen Secrets über den Deployment-Mechanismus: etwa Kubernetes Secrets, Docker Swarm Secrets oder eine Secret-Verwaltung des Cloud-Anbieters. Für ein Secret, das ausschließlich beim Build benötigt wird, nutzt BuildKit einen temporären Mount:

RUN --mount=type=secret,id=npmrc \
    npm ci

Das Secret wird bei diesem Schritt bereitgestellt, aber nicht in die erzeugte Image-Schicht kopiert. Zugangsdaten müssen außerdem nach einem möglichen Leak rotiert werden; ein neues Dockerfile entfernt keinen bereits veröffentlichten Layer.

Weniger Pakete, saubere Paketinstallation

Jedes zusätzliche Paket bringt Größe, Updates und potenzielle CVEs. Installiere daher nur, was der jeweilige Build-Schritt braucht. Bei Debian-Images gehört Aktualisieren, Installieren und Aufräumen in dieselbe RUN-Anweisung:

RUN apt-get update \
    && apt-get install --yes --no-install-recommends curl \
    && rm -rf /var/lib/apt/lists/*

Hier ist das Aufräumen wichtig, weil die Paketlisten sonst in der Schicht bleiben. „RUN-Befehle immer zusammenfassen“ ist dagegen keine allgemeine Regel: Zusammenfassen nur, wenn die Befehle einen temporären Zustand teilen – wie Paketlisten und deren Cleanup. Gute Lesbarkeit bleibt wichtiger als Layer-Akrobatik.

WORKDIR statt cd

WORKDIR setzt das Verzeichnis für alle folgenden Anweisungen und erstellt es bei Bedarf:

WORKDIR /app

Das ist robuster als ein RUN cd /app, denn ein cd gilt nur innerhalb dieses einen Shell-Prozesses. Absolute Pfade bleiben dadurch die Ausnahme statt Pflicht.

Healthchecks passend zur Plattform einsetzen

Ein laufender Prozess ist nicht zwingend eine funktionierende Anwendung. Ist ein HTTP-Endpunkt vorhanden, kann ein Docker-Healthcheck ihn prüfen:

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD node -e "fetch('http://localhost:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"

Der Endpunkt sollte keine Datenbankmigration auslösen und keine fremden Dienste teuer abfragen. Ein Healthcheck soll schnell beantworten, ob diese Instanz Anfragen bedienen kann.

Wichtig für Kubernetes: Kubernetes wertet die HEALTHCHECK-Anweisung eines Dockerfiles nicht aus. Dort gehören Liveness-, Readiness- und bei langsamen Starts Startup-Probes in das Deployment-Manifest.

Das gebaute Image prüfen

Ein Dockerfile kann gut aussehen und trotzdem mehr enthalten als erwartet. Prüfe daher das Artefakt, nicht nur den Text. Nach dem Build zeigen diese Befehle Größe und Schichten:

docker image ls my-app
docker history --no-trunc my-app

In der Historie sollten keine Zugangsdaten, lokalen Pfade oder unerwarteten Download-Befehle auftauchen. docker image inspect my-app zeigt unter anderem den konfigurierten Benutzer, Umgebungsvariablen und den Startbefehl. Das ist besonders nützlich, wenn ein USER-Wechsel zwar im Dockerfile steht, aber in einer späteren Stage verloren ging.

Danach den Container mit denselben Variablen und Ports wie im Deployment starten. Prüfe einen echten Request, die Logs und den Health-Status:

docker run --rm -p 3000:3000 --name my-app my-app
docker inspect --format '{{.State.Health.Status}}' my-app

Der zweite Befehl funktioniert nur mit definiertem HEALTHCHECK. Fehlt einer, ist das kein Grund, einen künstlichen Endpunkt einzubauen. Nicht jede Anwendung stellt HTTP bereit. Bei Worker-Prozessen oder CLI-Jobs sind Exit-Code, Queue-Verbindung oder die Probe des Orchestrators oft die passendere Betriebsprüfung.

Checkliste vor dem Push

• Base Image mit konkreter Version, bei Bedarf mit Digest
• .dockerignore enthält lokale Abhängigkeiten, Git-Daten und Secrets
• Build- und Runtime-Umgebung sind getrennt
• Runtime enthält keine Development-Abhängigkeiten und läuft nicht als Root
• Lockfile wird mit npm ci, pip --require-hashes oder dem jeweiligen Äquivalent genutzt
• Secrets kommen zur Laufzeit oder über BuildKit, nie per COPY, ENV oder ARG
• Healthcheck oder Orchestrator-Probes prüfen die tatsächliche Erreichbarkeit

Ein gutes Dockerfile ist kein Selbstzweck. Es sorgt dafür, dass dieselbe Anwendung mit weniger Überraschungen gebaut, ausgeliefert und betrieben wird. Starte mit kleinem Base Image, Multi-Stage Build, .dockerignore, Lockfile und Non-Root-User. Der Rest folgt aus den Anforderungen der Anwendung.

Weiterführende Quellen

• Dockerfile reference
• Docker build best practices
• Docker Build secrets
• OWASP Docker Security Cheat Sheet
• CIS Docker Benchmark