| name | devcontainer-setup |
| description | Best practices for creating and maintaining Dev Container configurations (.devcontainer/devcontainer.json). Use this when setting up a new devcontainer, adding features to an existing one, or adapting the container to a specific project type (Python/uv, Node.js, embedded/Yocto, Java, Rust, Terraform). Base image is always ubuntu:26.04 unless the project requires otherwise.
|
| user-invocable | true |
Dev Container Setup
Basis-Image
Standardmäßig wird Ubuntu 26.04 als Basis verwendet:
"image": "mcr.microsoft.com/devcontainers/base:ubuntu-26.04"
Alternativen nur bei zwingenden Gründen (z.B. Yocto benötigt spezifische Distro):
| Bild | Wann |
|---|
base:ubuntu-26.04 | Standard – alle neuen Projekte |
base:ubuntu-24.04 | Wenn ein Tool noch nicht Ubuntu 26 unterstützt |
base:debian-12 | Nur wenn Debian-spezifische Pakete benötigt werden |
Minimale devcontainer.json-Vorlage
Datei anlegen unter .devcontainer/devcontainer.json:
{
"name": "<Projektname>",
"image": "mcr.microsoft.com/devcontainers/base:ubuntu-26.04",
"features": {
"ghcr.io/devcontainers/features/common-utils:2": {
"installZsh": true,
"configureZshAsDefaultShell": true,
"installOhMyZsh": true,
"installOhMyZshConfig": true,
"upgradePackages": false,
"username": "ubuntu"
},
"ghcr.io/devcontainers/features/github-cli:1": {},
"ghcr.io/devcontainers/features/git:1": {}
},
"remoteUser": "ubuntu",
"customizations": {
"vscode": {
"extensions": [],
"settings": {}
}
}
}
common-utils und git sind immer dabei. Alle weiteren Features werden
projektabhängig ergänzt (siehe Abschnitt "Feature-Auswahl nach Projekttyp").
Feature-Auswahl nach Projekttyp
Python-Projekte (mit uv)
"ghcr.io/devcontainers/features/python:1": {
"version": "3.12",
"installTools": false
},
"ghcr.io/devcontainers/features/github-cli:1": {}
installTools: false – pip/virtualenv werden nicht benötigt, da uv alles übernimmt.
uv selbst im postCreateCommand installieren:
"postCreateCommand": "curl -LsSf https://astral.sh/uv/install.sh | sh"
Node.js-Projekte
"ghcr.io/devcontainers/features/node:1": {
"version": "22",
"nodeGypDependencies": false
}
Projekte mit Docker-Builds (CI-ähnlich)
"ghcr.io/devcontainers/features/docker-in-docker:2": {
"version": "latest",
"moby": true
}
Docker-in-Docker vs. Docker-outside-of-Docker: docker-in-docker startet
eine eigene Docker-Instanz im Container. docker-outside-of-docker teilt den
Host-Socket. Für CI-ähnliche Builds ist docker-in-docker zu bevorzugen.
Embedded / Yocto-Projekte
"ghcr.io/devcontainers/features/github-cli:1": {}
Yocto-Build-Dependencies über postCreateCommand als apt installieren:
"postCreateCommand": "sudo apt-get update && sudo apt-get install -y gawk wget git-core diffstat unzip texinfo gcc-multilib build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping file lz4 zstd"
Java-Projekte
"ghcr.io/devcontainers/features/java:1": {
"version": "21",
"jdkDistro": "ms"
}
Kubernetes / Terraform
"ghcr.io/devcontainers/features/kubectl-helm-minikube:1": {
"version": "latest",
"helm": "latest",
"minikube": "none"
},
"ghcr.io/devcontainers/features/terraform:1": {}
Rust-Projekte
"ghcr.io/devcontainers/features/rust:1": {
"version": "latest",
"profile": "minimal"
}
Projekt-Feature: precommit-setup (lokal)
Für Projekte mit eigenem ./features/precommit-setup:
"./features/precommit-setup": {
"version": "latest",
"installMarkdownlint": true,
"installPyYAML": true
}
Lokale Features liegen unter .devcontainer/features/<name>/devcontainer-feature.json.
Vollständiges Beispiel: Python-Projekt mit CI-Fähigkeit
{
"name": "my-python-project",
"image": "mcr.microsoft.com/devcontainers/base:ubuntu-26.04",
"features": {
"ghcr.io/devcontainers/features/common-utils:2": {
"installZsh": true,
"configureZshAsDefaultShell": true,
"installOhMyZsh": true,
"installOhMyZshConfig": true,
"upgradePackages": false,
"username": "ubuntu"
},
"ghcr.io/devcontainers/features/git:1": {},
"ghcr.io/devcontainers/features/github-cli:1": {},
"ghcr.io/devcontainers/features/python:1": {
"version": "3.12",
"installTools": false
},
"ghcr.io/devcontainers/features/docker-in-docker:2": {}
},
"postCreateCommand": "curl -LsSf https://astral.sh/uv/install.sh | sh && uv sync",
"remoteUser": "ubuntu",
"customizations": {
"vscode": {
"extensions": [
"ms-python.python",
"ms-python.vscode-pylance",
"charliermarsh.ruff",
"GitHub.copilot",
"GitHub.copilot-chat"
],
"settings": {
"python.defaultInterpreterPath": ".venv/bin/python",
"[python]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "charliermarsh.ruff"
}
}
}
}
}
Vollständiges Beispiel: Node.js / Nuxt-Projekt
{
"name": "my-nuxt-project",
"image": "mcr.microsoft.com/devcontainers/base:ubuntu-26.04",
"features": {
"ghcr.io/devcontainers/features/common-utils:2": {
"installZsh": true,
"configureZshAsDefaultShell": true,
"installOhMyZsh": true,
"installOhMyZshConfig": true,
"upgradePackages": false,
"username": "ubuntu"
},
"ghcr.io/devcontainers/features/git:1": {},
"ghcr.io/devcontainers/features/github-cli:1": {},
"ghcr.io/devcontainers/features/node:1": {
"version": "22"
}
},
"postCreateCommand": "npm ci",
"remoteUser": "ubuntu",
"forwardPorts": [3000],
"customizations": {
"vscode": {
"extensions": [
"Vue.volar",
"GitHub.copilot",
"GitHub.copilot-chat",
"dbaeumer.vscode-eslint"
]
}
}
}
Aktuelle Feature-Versionen (Stand 2026-04-27)
Immer vor Eintragen auf dem aktuellen Stand prüfen:
curl -s "https://raw.githubusercontent.com/devcontainers/features/main/src/<feature>/devcontainer-feature.json" \
| python3 -c "import json,sys; d=json.load(sys.stdin); print(d['version'])"
| Feature | Version | OCI-Referenz |
|---|
common-utils | 2.5.7 | ghcr.io/devcontainers/features/common-utils:2 |
git | 1.3.5 | ghcr.io/devcontainers/features/git:1 |
github-cli | 1.1.0 | ghcr.io/devcontainers/features/github-cli:1 |
python | 1.8.0 | ghcr.io/devcontainers/features/python:1 |
node | 1.7.1 | ghcr.io/devcontainers/features/node:1 |
docker-in-docker | 2.16.1 | ghcr.io/devcontainers/features/docker-in-docker:2 |
rust | 1.5.0 | ghcr.io/devcontainers/features/rust:1 |
java | 1.8.0 | ghcr.io/devcontainers/features/java:1 |
kubectl-helm-minikube | 1.3.1 | ghcr.io/devcontainers/features/kubectl-helm-minikube:1 |
terraform | 1.4.2 | ghcr.io/devcontainers/features/terraform:1 |
Renovate hält die Major-Pins (:1, :2) automatisch aktuell, wenn der
devcontainer Manager in renovate.json aktiv ist (in config:standard enthalten).
Häufige Fehler & Fixes
| Fehler | Ursache | Fix |
|---|
| Container baut, aber User hat keine sudo-Rechte | remoteUser nicht gesetzt | "remoteUser": "ubuntu" in devcontainer.json |
postCreateCommand schlägt fehl | Läuft als root, PATH nicht gesetzt | "remoteUser" vor postCreateCommand sicherstellen |
| Oh-My-Zsh startet nicht | username in common-utils falsch | Muss mit remoteUser übereinstimmen (ubuntu) |
docker: command not found im Container | Feature fehlt | docker-in-docker oder docker-outside-of-docker hinzufügen |
| Feature-Version nicht auflösbar | Major-Tag veraltet | Versionstabelle oben prüfen; Major-Tag im Ref aktualisieren |
uv nicht gefunden nach postCreateCommand | PATH nicht neu geladen | source $HOME/.local/bin/env oder neues Terminal öffnen |
