Development container standardisation using Dev Containers (formerly devcontainers) is the solution to the "works on my machine" problem that has plagued engineering teams for decades. A Dev Container defines the complete development environment — language runtime, tools, extensions, environment variables, ports, and post-creation setup — as code in a .devcontainer/devcontainer.json file committed to the repository. Every developer who opens the project gets an identical, reproducible environment in minutes. This guide covers Dev Container architecture, configuration patterns, and enterprise deployment with GitHub Codespaces and VS Code Remote.
What Are Dev Containers?
devcontainer.json. The container provides: the language runtime (Node.js 22, Python 3.12, Java 21, etc.), development tools (CLI tools, test runners, linters), VS Code extensions pre-installed and configured, port forwarding, environment variables, and post-creation setup scripts. Developers open the repo in VS Code or GitHub Codespaces, accept the "Reopen in Container" prompt, and have a fully configured environment in 2–5 minutes — regardless of their host OS.devcontainer.json Configuration Reference
| Field | Purpose | Example |
|---|---|---|
| image / build | Base Docker image or Dockerfile to build from | "image": "mcr.microsoft.com/devcontainers/node:22" |
| features | Add tools/runtimes to base image — no Dockerfile needed for common tools | "ghcr.io/devcontainers/features/docker-in-docker": {} |
| customizations.vscode.extensions | VS Code extensions installed in container | ESLint, Prettier, GitLens, your language extension |
| customizations.vscode.settings | VS Code settings applied in container — enforce code style | Format on save, linter rules, tab size |
| forwardPorts | Ports exposed from container to host | [3000, 5432] for app + database |
| postCreateCommand | Runs once after container creation — install dependencies | "npm install" or "./scripts/setup.sh" |
| remoteUser | User to run as in container — non-root for security | "node" |
In your project root, create .devcontainer/devcontainer.json. Minimum viable config: {"image": "mcr.microsoft.com/devcontainers/<language>:<version>", "postCreateCommand": "<install-command>"}. Microsoft provides pre-built base images for all major stacks at mcr.microsoft.com/devcontainers/. Add Features for tools you need — avoid custom Dockerfiles unless necessary. The Dev Containers extension in VS Code provides a generator UI: Cmd+Shift+P → "Dev Containers: Add Dev Container Configuration Files". Commit to the repository immediately.
For projects requiring a database, cache, or other services: use docker-compose.yml alongside devcontainer.json. Add "dockerComposeFile": "docker-compose.yml" and "service": "app" to devcontainer.json — the Dev Container runs in the app service while docker-compose brings up PostgreSQL, Redis, etc. alongside. Developers get a complete local stack with one container start. Commit the docker-compose.yml with dev-appropriate configs (no persistent volumes, seeded test data, exposed ports). Our DevOps team implements Dev Container programmes for enterprise engineering organisations.
For GitHub Codespaces deployment: configure organisation-level policies — allowed machine types, idle timeout (default 30 min, set to 60 for developer comfort), retention period for stopped codespaces (14–30 days). Use Dev Container templates at the organisation level for standardised starting points. Publish internal Dev Container features to your GitHub Container Registry for tools unique to your organisation (internal CLI tools, custom certificates, VPN client). Monitor Codespaces cost via the GitHub billing dashboard — set per-user spending limits.
Our DevOps and software development teams implement Dev Container programmes for enterprise engineering organisations — devcontainer.json authoring, Codespaces policy configuration, and developer enablement. Book a free advisory session.