Docker init: So initialisierst du ein Projekt mit Docker (Schritt-für-Schritt-Anleitung)

Aus irgendeinem Grund dauert es immer länger als nötig, ein neues Projekt mit Docker aufzusetzen.

Du googelst ein Template, fügst es ein, änderst ein paar Zeilen und hoffst aufs Beste. Der Build schlägt fehl, also schraubst du nach und wiederholst das Spiel, bis es läuft. Jedes neue Projekt startet gleich – mit einer leeren Datei und der vagen Erinnerung daran, was letztes Mal funktioniert hat. Das ist eindeutig ein Setup-Problem, und Docker ist nicht schuld.

Die gute Nachricht: docker init behebt das. Der CLI-Befehl erkennt deinen Projekttyp und erzeugt ein Dockerfile, eine .dockerignore und eine Compose-Datei.

In diesem Artikel zeige ich dir, wie docker init funktioniert, wie du es Schritt für Schritt an einem echten Python-Projekt nutzt und wann es das richtige Werkzeug ist.

Bist du neu bei Docker und Containerisierung? Erfahre, warum es zum Werkzeugkasten von Datenprofis gehört – mit unserem Introduction to Docker Kurs.

Was ist Docker init

docker init ist ein CLI-Tool, das die Docker-Konfiguration für dein Projekt aufsetzt. Es erzeugt die Dateien, die du brauchst, um deine App zu containerisieren. Vorlagen oder Copy-Paste entfallen damit.

Es erstellt drei Dateien:

• Dockerfile – definiert, wie dein Container-Image gebaut wird
• .dockerignore – sagt Docker, welche Dateien aus dem Build-Kontext herauszuhalten sind
• compose.yml – optional, aber praktisch für Multi-Service-Setups

Das Clevere ist die automatische Projekterkennung. docker init analysiert deine Struktur und erkennt deinen Stack – Python, Node.js, Go und weitere. Dann generiert es passende Dateien für diesen Stack statt eines generischen Templates.

Es ist kein Deployment-Tool und verwaltet keine Container in Produktion. Es bringt nur deine Konfiguration an den Start, damit du dich auf die eigentliche Arbeit konzentrieren kannst.

So funktioniert Docker init

docker init folgt bei jedem Lauf einem Ablauf in vier Schritten.

Zuerst führst du docker init im Projektordner aus. Docker scannt das Verzeichnis, erkennt den Projekttyp und wählt das passende Konfigurationstemplate. Danach führt dich ein kurzer interaktiver Dialog durch ein paar Fragen – etwa auf welchem Port deine App läuft und mit welchem Befehl sie startet. Sobald du antwortest, werden die Dateien erzeugt.

Das Ganze dauert weniger als eine Minute.

Die Eingaben sind einfach und selten erklärungsbedürftig. Du kannst die Standardwerte mit Enter übernehmen oder eigene Werte eintragen, wenn sie nicht passen. 

So sieht der erste Start des Befehls aus:

Docker-init-Setup-Bildschirm

Ich zeige dir den Ablauf als Nächstes genauer.

Docker init Schritt für Schritt nutzen

So kommst du vom Projektordner zum laufenden Container.

Schritt 1: In dein Projektverzeichnis wechseln

Öffne dein Terminal und wechsle ins Projekt-Root – also den Ordner mit deinem Anwendungscode.

cd /path/to/your/project

docker init erzeugt Dateien relativ zu dem Verzeichnis, in dem du es ausführst. Achte also darauf, dass du im richtigen Ordner bist.

Schritt 2: Docker init ausführen

Führe folgenden Befehl aus:

docker init

Docker scannt den Projektordner, erkennt deinen Stack und startet den interaktiven Setup-Dialog.

Schritt 3: Die Fragen beantworten

docker init stellt dir ein paar Fragen:

• Anwendungsplattform – die Sprache bzw. das Framework deines Projekts (Python, Node.js, Go usw.)
• Port – der Port, auf dem deine App lauscht
• Startbefehl – der Befehl, den Docker zum Start deiner App ausführen soll

Du kannst die vorgeschlagenen Defaults mit Enter übernehmen oder eigene Werte eingeben. Wenn docker init deinen Stack erkennt, reichen die Defaults meist für den Start.

Schritt 4: Die erzeugten Dateien prüfen

Nach dem Dialog schreibt docker init drei Dateien in deinen Projektordner:

.
├── Dockerfile
├── .dockerignore
└── compose.yaml

Öffne die Dateien und lies sie durch. Die generierten Dateien enthalten Kommentare, die jede Zeile erklären. Nimm dir kurz Zeit, das zu verstehen, bevor du weiterbaust.

Schritt 5: Container bauen und starten

Baue und starte deinen Container mit Docker Compose:

docker compose up --build

Der Schalter --build weist Docker an, das Image aus deinem Dockerfile zu bauen, bevor der Container startet. Läuft er, ist deine App über den in Schritt 3 angegebenen Port erreichbar.

Unterstützte Projekttypen in Docker init

docker init unterstützt out of the box die gängigsten Stacks. Hier ein paar Beispiele:

• Python
• Node.js
• Go
• Java
• .NET

Die Erkennung läuft automatisch. Wenn du docker init startest, scannt es deinen Ordner nach sprachspezifischen Dateien – etwa requirements.txt für Python oder package.json für Node.js – und wählt auf dieser Basis das passende Template.

Jedes Template ist auf den Stack zugeschnitten. Ein Python-Projekt bekommt ein anderes Base-Image, andere Installationsschritte und Startbefehle als ein Go-Projekt. Es ist kein One-Size-Fits-All-Dockerfile mit einer ausgetauschten Sprachvariable – die Struktur ändert sich je nach Anwendung.

Wenn docker init deinen Stack nicht erkennt, kannst du ihn im Dialog manuell auswählen.

Von Docker init erzeugte Dateien

docker init erzeugt drei Dateien, die jeweils eine andere Rolle im Setup haben.

Dockerfile

Das Dockerfile definiert, wie Docker dein Container-Image baut. Es legt fest, von welchem Base-Image gestartet wird, wie Abhängigkeiten installiert werden und welcher Befehl beim Containerstart ausgeführt wird.

So kann ein generiertes Python-Dockerfile aussehen:

FROM python:3.14-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

Prüfe die Datei vor dem Build. Das generierte Ergebnis ist ein guter Startpunkt, aber oft sind Anpassungen nötig – zum Beispiel Umgebungsvariablen oder eine andere Base-Image-Version.

.dockerignore

Die .dockerignore-Datei sagt Docker, welche Dateien aus dem Build-Kontext ausgeschlossen werden. Das ist der Dateisatz, den Docker beim Image-Bau an die Build-Engine sendet.

Ohne sie würde Docker alles im Projektordner ins Image kopieren – inklusive .git, node_modules oder lokaler Konfigs, die in Produktion nichts verloren haben. Das bläht das Image auf und kann versehentlich Dateien einschließen.

Eine typische .dockerignore sieht so aus:

.git
.env
__pycache__
*.pyc
node_modules

Docker-Compose-Datei

Die compose.yaml-Datei dient zum Starten von Multi-Container-Setups. Sie definiert Services, Ports, Volumes und die Vernetzung der Container.

Für eine einfache Single-Container-App brauchst du sie nicht zwingend. Aber sobald Datenbank, Cache oder andere Dienste dazukommen, konfigurierst du alles zentral in Compose.

Beispiel: Docker init mit einem Python-Projekt

Lass uns docker init an einem echten Projekt laufen. Ich nutze eine minimale FastAPI-App mit einer einzigen Route.

So sieht die Struktur vor docker init aus:

my-fastapi-app/
├── app.py
└── requirements.txt

app.py hat eine einzige Hello-World-Route:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, World!"}

Und requirements.txt enthält diese zwei Abhängigkeiten:

fastapi
uvicorn

docker init ausführen

Wechsle in den Projektordner und führe aus:

docker init

Docker init hat das Projekt erkannt

docker init erkennt Python anhand der requirements.txt und stellt dir ein paar Fragen. So sehen die Prompts aus – und so kannst du antworten:

Docker-init-Eingaben für ein Python-Projekt

Was generiert wird

Nach der Beantwortung der Fragen sieht dein Projektordner so aus:

Neue Projektordner-Struktur

Es gibt drei neue Dateien. Schauen wir sie uns an.

Das Dockerfile

# syntax=docker/dockerfile:1

ARG PYTHON_VERSION=3.14
FROM python:${PYTHON_VERSION}-slim as base

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

WORKDIR /app

ARG UID=10001
RUN adduser \
    --disabled-password \
    --gecos "" \
    --home "/nonexistent" \
    --shell "/sbin/nologin" \
    --no-create-home \
    --uid "${UID}" \
    appuser

RUN --mount=type=cache,target=/root/.cache/pip \
    --mount=type=bind,source=requirements.txt,target=requirements.txt \
    python -m pip install -r requirements.txt

USER appuser

COPY . .

EXPOSE 8000

CMD uvicorn 'app:app' --host=0.0.0.0 --port=8000

Ein paar Dinge stechen heraus: PYTHONDONTWRITEBYTECODE=1 verhindert, dass Python .pyc-Dateien schreibt, und PYTHONUNBUFFERED=1 sorgt dafür, dass Logs in Echtzeit erscheinen statt gepuffert zu werden – beides sinnvolle Defaults für containerisierte Apps.

Der adduser-Block erzeugt einen nicht privilegierten Nutzer appuser zum Ausführen der Anwendung. Standardmäßig laufen Docker-Container als root, was ein Sicherheitsrisiko ist. Ein Non-Root-User begrenzt, was ein Angreifer im Fall eines Ausbruchs anrichten kann.

Der Schalter --mount=type=cache beim pip install weist Docker an, heruntergeladene Pakete zwischen Builds zu cachen. Folge-Builds müssen Abhängigkeiten dann nicht erneut laden – das beschleunigt den Prozess.

Die .dockerignore

**/.DS_Store
**/__pycache__
**/.venv
**/.env
**/.git
**/.gitignore
**/node_modules
**/Dockerfile*
**/compose.y*ml
README.md

Die .dockerignore schließt Dateien aus, die nicht ins Image gehören. Lokale Umgebungsdateien wie .env, Versionskontrollordner wie .git und Python-Caches wie __pycache__ werden übersprungen. Auch das Dockerfile und die compose.yaml selbst werden ausgeschlossen – sie werden im Image nicht benötigt.

Die compose.yaml

services:
  server:
    build:
      context: .
    ports:
      - 8000:8000

Die Compose-Datei definiert deine App als Service server, baut sie aus dem Dockerfile im aktuellen Verzeichnis und mappt Port 8000 des Hosts auf Port 8000 im Container.

Alle drei generierten Dateien enthalten Kommentare, die ich hier zur Übersichtlichkeit weggelassen habe.

Führe docker compose up --build aus – deine FastAPI-App ist dann unter http://localhost:8000 erreichbar.

FastAPI-App läuft im Container

Docker init vs. manuelles Dockerfile-Setup

Beide Wege liefern dir ein funktionierendes Dockerfile. Die Frage ist, wie viel Kontrolle du brauchst und wie schnell du starten willst.

Docker init

docker init ist der schnellere Weg. Du beantwortest ein paar Fragen und bekommst in unter einer Minute eine funktionierende, solide konfigurierte Basis. Die Dateien folgen den Best Practices von Docker – Non-Root-User, Build-Caching, sinnvolle .dockerignore-Muster – du startest nicht bei null.

Ideal, wenn du ein neues Projekt aufsetzt, jemand ins Team einarbeitest oder einfach eine belastbare Grundlage ohne Boilerplate-Aufwand willst.

Aber die Flexibilität ist begrenzt. Die Templates decken gängige Stacks gut ab, bleiben aber Templates. Hat dein Projekt eine ungewöhnliche Struktur oder spezielle Build-Anforderungen, stößt docker init an Grenzen.

Manuelles Setup

Schreibst du dein Dockerfile selbst, hast du die volle Kontrolle über jede Schicht, jede Anweisung und jeden Build-Schritt. Du kannst Multi-Stage-Builds implementieren, eigene Base-Images nutzen oder das Caching feintunen – Dinge, die docker init nicht vorwegnehmen kann.

Dafür musst du wissen, was du tust. Ein schlecht geschriebenes Dockerfile kann aufgeblasene Images, Sicherheitslücken oder schwer zu debuggende Fehler verursachen – besonders ohne Erfahrung.

Welche Option wählen

So kannst du es dir merken:

Vergleich: Docker init vs. manuelles Setup

Ein guter Ansatz ist: Starte mit docker init und passe die generierten Dateien später an, wenn die Anforderungen wachsen.

Wann du Docker init nutzen solltest

docker init ist nicht in jeder Situation das richtige Tool. Hier passt es – und hier nicht.

Nutze docker init, wenn:

• Du ein neues Projekt startest: Du bekommst deine Docker-Konfiguration in unter einer Minute zum Laufen und kannst dich aufs Coden statt aufs Container-Setup konzentrieren

• Du Docker lernst: Die generierten Dateien sind gut kommentiert und folgen Best Practices. Ein besserer Startpunkt als ein zufälliger Stack-Overflow-Schnipsel

• Du prototypisierst: Wenn du schnell eine containerisierte Umgebung brauchst und Feintuning zweitrangig ist, liefert docker init etwas, das funktioniert

• Du im Team standardisieren willst: Statt dass jede Person ein eigenes Dockerfile baut, liefert docker init allen den gleichen soliden Ausgangspunkt

Du solltest docker init hingegen meiden, wenn:

• Du Multi-Stage-Builds brauchst: Wenn du die Imagegröße optimierst, indem du den Build in Stufen trennst – Kompilieren hier, Ausführen dort –, musst du das manuell schreiben. Das generierte Dockerfile ist einstufig

• Du komplexe Produktionsanforderungen hast: Eigene Base-Images, fortgeschrittenes Caching, unübliche Projektlayouts – das kann docker init nicht vorwegnehmen. Da ist es schneller, das Dockerfile direkt selbst zu schreiben

Kurz gesagt: docker init ist ein Startpunkt. Nutze es zum Loslegen und bearbeite die Dateien, wenn die Anforderungen steigen.

Einschränkungen von Docker init

Mit wachsendem Projekt stößt du auf Grenzen. Hier ein paar davon.

Die generierten Dateien sind templatebasiert. Sie decken die häufigsten Fälle pro Stack ab – gut für Standards, weniger gut außerhalb dieses Rahmens. Hat dein Projekt eine ungewöhnliche Struktur, werden die Dateien das eventuell nicht berücksichtigen.

Außerdem gilt: Nacharbeit ist fast immer nötig. Defaults sind gut, aber eben Defaults. Du wirst Base-Image-Versionen fixieren, Umgebungsvariablen anpassen oder den Startbefehl ändern müssen. Betrachte die generierten Dateien als ersten Entwurf – nicht mehr.

docker init unterstützt auch keine fortgeschrittenen Build-Muster. Multi-Stage-Builds, eigene Build-Argumente, bedingte Logik und andere Techniken für Produktions-Images liegen außerhalb des Umfangs. Wenn du das brauchst, schreibst du das Dockerfile ohnehin selbst.

All das macht docker init nicht schlecht. Es geht um die richtige Erwartung: Es nimmt dir die leere Seite, aber nicht das Verständnis dafür ab, was in deinem Dockerfile steht.

Best Practices nach Docker init

Die von docker init erzeugten Dateien sind der Anfang. So machst du sie produktionstauglich.

• Generierte Dateien durchgehen: Lies Dockerfile, .dockerignore und compose.yaml Zeile für Zeile. Dank Kommentaren geht das schnell. Verstehe, was drinsteht, bevor du darauf aufbaust

• Imagegröße optimieren: Das Default-Base-Image ist python:3.x-slim – schon schlank. Du kannst weiter optimieren, indem du die .dockerignore schärfst und nur wirklich benötigte Dateien ins Image kopierst

• Secrets und umgebungsspezifische Werte in Umgebungsvariablen auslagern: Keine API-Keys, DB-URLs oder Flags im Dockerfile hardcoden. Nutze Umgebungsvariablen – lokal per .env, in Produktion über das Secret-Management deiner Plattform

• Lokal testen, bevor du etwas pushst: Führe docker compose up --build aus und prüfe, ob sich die App im Container wie außerhalb verhält. Checke Logs, Endpunkte und das Port-Mapping

• Build-Schritte mit dem Wachstum verfeinern: Das generierte Dockerfile installiert Abhängigkeiten in einer Schicht. Reife Projekte profitieren von Schichtreihenfolgen: Schritte, die sich selten ändern, kommen nach vorn, damit Docker sie cachen kann. Wenn Builds langsamer werden, ist das meist die erste Stellschraube

Häufige Probleme und Troubleshooting

Wie immer in der Tech-Welt kann auch mal etwas schiefgehen. Darauf solltest du achten – und so behebst du es.

Falsche Projekterkennung

Wenn docker init den falschen Stack erkennt, erzeugt es unpassende Dateien. Das passiert oft bei gemischten Projektordnern oder wenn die gesuchte Datei fehlt – etwa requirements.txt in Python oder package.json in Node.js.

Wähle in der Abfrage einfach die korrekte Plattform manuell statt die Erkennung zu übernehmen.

Port-Konflikte

Wenn der Container startet, aber die App nicht erreichbar ist oder Docker meldet, der Port sei bereits belegt, nutzt wahrscheinlich ein anderer Prozess denselben Port.

Beende den kollidierenden Prozess oder ändere den Host-Port in compose.yaml:

ports:
  - 8001:8000  # mappt Host-Port 8001 auf Container-Port 8000

Links steht der Port auf deinem Rechner. Rechts der Port im Container, auf dem deine App lauscht.

Fehlende Abhängigkeiten

Wenn der Container baut, aber beim Start abstürzt, fehlen oft Abhängigkeiten. Prüfe, ob deine requirements.txt (oder Äquivalent) vollständig und aktuell ist. Wenn du lokal ein Paket hinzugefügt, aber die Datei nicht aktualisiert hast, fehlt es im Container.

Nutze docker compose logs, um die Fehlermeldung zu sehen:

docker compose logs

Die Meldung verrät dir in der Regel, welches Paket fehlt.

Container startet nicht

Wenn der Container gar nicht startet, liegt es fast immer an der CMD-Zeile im Dockerfile. Prüfe, ob der Startbefehl deiner tatsächlichen Startweise entspricht.

Für das FastAPI-Beispiel sollte er so aussehen:

CMD uvicorn 'app:app' --host=0.0.0.0 --port=8000

Wenn die Einstiegsdatei anders heißt oder der Modulpfad nicht stimmt, beendet sich der Container. Korrigiere CMD, baue mit docker compose up --build neu und prüfe die Logs erneut.

Fazit

docker init ersetzt kein tiefes Docker-Verständnis, aber es nimmt dir das Problem der leeren Seite.

Mit einem einzigen Befehl bekommst du ein funktionierendes Dockerfile, eine .dockerignore und eine compose.yml – alles nach Dockers Best Practices. Das ist eine starke Basis für jedes neue Projekt und besser als ein kopiertes Template aus Stack Overflow oder ChatGPT.

Aber bleib nicht dabei stehen. Die generierten Dateien sind zum Anpassen gedacht. Prüfe sie, verfeinere die Build-Schritte, pinne deine Base-Image-Version und füge Umgebungsvariablen hinzu. Mit dem Wachstum deines Projekts wirst du dich immer weiter von den Defaults entfernen.

Wenn du die Docker-Grundlagen kennst, ist der nächste logische Schritt, Multi-Stage-Builds, Networking-Tools und Docker Compose zu lernen – all das behandeln wir im Intermediate Docker Kurs.