Wie du lokale dev‑environments mit devcontainer und docker so einrichtest, dass onboarding zehnmal schneller geht

Ich erzähle dir, wie ich lokale Entwicklungsumgebungen mit DevContainers und Docker so aufgebaut habe, dass Onboarding-Prozesse gefühlt zehnmal schneller laufen. In meinen Projekten – von kleinen Single-Developer-Repos bis zu Teamprojekten mit mehreren Services – war die größte Zeitfresserin immer: „Warum läuft es bei dir, aber nicht bei mir?“ DevContainers haben das nicht nur technisch gelöst, sondern auch die Kommunikation und Produktivität im Team drastisch verbessert.

Warum DevContainers + Docker?

Docker sorgt dafür, dass Abhängigkeiten isoliert laufen. DevContainers (die auf Visual Studio Code Remote - Containers aufbauen) liefern zusätzlich eine reproduzierbare Entwicklungsumgebung: Editor-Extensions, bestimmte Node-/Python-Versionen, Linter, Build-Tools und sogar Datenbanken sind bereits vorkonfiguriert. Für Neuzugänge bedeutet das: Kein langes Setup, keine mysteriösen „it works on my machine“-Mails.

Aus meiner Erfahrung spart eine funktionierende DevContainer-Konfiguration vor allem drei Dinge: Zeit (kein manuelles Installieren), Fehler (gleiches System für alle) und mentale Belastung (onboarding ist weniger frustrierend).

Was gehört in einen guten DevContainer?

Ein brauchbarer DevContainer ist mehr als nur ein Dockerfile. Ich packe typischerweise folgende Bestandteile rein:

• Basis-Image (node, python, golang, oder ein custom image mit build-tools)
• IDE-Extensions (z. B. ESLint, Prettier, Python, GitLens)
• Dev-Dependencies (npm/yarn/pip install, Rust toolchain, etc.)
• Database-Services über docker-compose oder Docker-Compose-Profile (Postgres, Redis, Elasticsearch)
• Start-Skripte für common tasks (db:migrate, seed, start)
• Dokumentation im Repo (kurze README im .devcontainer-Ordner)

Beispiel-Aufbau: minimaler .devcontainer

Ich platziere die DevContainer-Konfiguration im Ordner .devcontainer/. Typische Dateien:

• devcontainer.json – Hauptkonfiguration
• Dockerfile – optional, wenn du ein eigenes Image bauen willst
• docker-compose.yml – für abhängige Services (Datenbanken, Maildev)
• README.md – kurze Schritte für Erste Schritte

Wichtig: Halte die devcontainer.json kompakt und nutze Skripte, um komplexe Setup-Schritte auszulagern. So bleibt die Datei lesbar und wartbar.

Konkrete Tipps & Best Practices

• Images versionieren: Nutze feste Versionen (z. B. node:18-bullseye) – vermeide "latest".
• Cache nutzen: Paketmanager-Cache und Layer sinnvoll anordnen, damit rebuilds schnell sind.
• Persistent Data: Datenbanken in Named Volumes, damit Seeds nicht bei jedem Start verloren gehen.
• Dev vs Prod: Keine Produktions-Keys im Container. Nutze Beispiel-Env-Dateien (.env.example) und secrets bei Bedarf.
• Health Checks: docker-compose healthcheck für Services, damit Start-Skripte warten, bis DB ready ist.
• Oneliner fürs Team: Ein Skript wie ./dev up oder ein Makefile-Target reduziert Kommunikationsaufwand.

Praktisches Beispiel: devcontainer.json (Kerngedanke)

Inhalt, den ich standardmäßig verwende (verkürzt):

• image oder build (auf Dockerfile)
• postCreateCommand: Install, migration & build
• extensions: eine Liste nützlicher VS Code Extensions
• forwardPorts: App-Ports, Debugger-Ports
• mounts: evtl. für lokale Caches

Beispiel-Workflow: nach Clone git clone, dann code . öffnet VS Code, der Container wird gebaut und automatisch die postCreateCommand ausgeführt (Dependencies installieren, DB anlegen, Seeds laufen lassen). Das ist die Magie: Entwickler starten mit einer lauffähigen App binnen Minuten.

Docker-Compose für abhängige Services

Für Projekte mit Datenbank, Redis oder einem Message-Broker empfiehlt sich eine docker-compose-Datei, die als Dev Profile in devcontainer.json eingebunden wird. So startet jeder Entwickler dieselben Services im selben Netzwerk, und Services erreichen sich immer unter denselben Hostnamen (z. B. db:5432).

Onboarding-Checklist, die bei mir funktioniert

• Clone Repo
• Öffne Repo in VS Code (Remote – Container startet automatisch)
• Warte bis postCreateCommand durchgelaufen ist
• Führe ein kurzes Smoke-Test-Skript aus (./dev smoke)
• Schau in .devcontainer/README.md für Troubleshooting

Häufige Stolperfallen und wie ich sie löse

Ein paar Probleme wiederholen sich in jedem Team:

• Langsame Builds: Ich splitte Dockerfiles in kleinere Layer, nutze multi-stage builds und speichere node_modules/cache in Volumes, wenn sinnvoll.
• Editor-Performance: Bei großen Repos setze ich remote.extensionKind und schließe bestimmte Ordner vom Index aus.
• Secrets: Niemals Geheimnisse im Repo. Stattdessen .env.example und Hinweise zur Nutzung von Secret-Managern (GitHub Actions secrets, Vault, pass).
• Platform Differences: Nutze Linux-basierte Container, launche lokal unter Docker Desktop oder DevDroid, und dokumentiere, wenn Mac-spezifische Workarounds nötig sind (z. B. fsevents).

Tools, die ich kombiniere

• Visual Studio Code + Remote - Containers (einfachste UX)
• Docker Desktop / colima / Docker Engine auf CI
• docker-compose oder docker compose v2
• Make oder just für bequeme CLI-Wrapper
• Optional: Nix + devcontainers für noch deterministischere Toolchains

Messbar: Wie viel schneller wird Onboarding?

Ich messe das pragmatisch: Zeit bis zu einem erfolgreichen Pull-Request oder bis ein Feature lokal läuft. Vor DevContainers lagen wir oft bei mehreren Stunden teils verteilter Setups. Mit einer gut gepflegten DevContainer-Konfiguration sind erste PRs oft innerhalb von 30–90 Minuten möglich — je nach Komplexität des Projekts. Das ist weniger ein magischer Faktor als ein realer Gewinn: weniger Frustration, weniger Context-Switching, mehr Fokus auf Code.

Wenn du willst, kann ich dir ein Starter-Template für dein Tech-Stack (z. B. Node + Postgres + Redis) zusammenstellen oder ein Review eurer aktuellen .devcontainer-Dateien machen. So stelle ich sicher, dass die Konfiguration robust, performant und für neue Mitarbeitende wirklich schnell nutzbar ist.