Dev containers: devcontainer.json as a reproducible development environment

What it is

The Development Container Specification describes itself as an open specification for enriching containers with development specific content and settings. The metadata lives in .devcontainer/devcontainer.json: an image or build.dockerfile (or dockerComposeFile for multi-service setups), features (reusable install steps such as a language toolchain or a CLI, referenced by registry path), forwardPorts, containerEnv and remoteEnv, remoteUser, customizations for editor-specific settings, and lifecycle commands. The reference documents their order: initializeCommand runs on the host; inside the container, onCreateCommand, updateContentCommand and postCreateCommand finalise setup when the container is created; postStartCommand runs on every start and postAttachCommand whenever a tool attaches. GitHub's documentation calls devcontainer.json the primary file of a Codespaces configuration, and the reference notes that cloud services may run the create-time commands when caching or prebuilding a container, so those commands typically have no access to user-scoped secrets.

Why it matters

"Works on my machine" is usually a toolchain-version problem. A dev container pins the operating system, runtime and CLI tools in one file that is versioned with the code; a newcomer, a hosted workspace and a coding agent all start from the same image instead of from whatever the host happens to have. Because CI can run the same image, the local environment and the pipeline stop drifting apart.

How to apply

• Start from a Dockerfile you already trust (the production base image where sensible) rather than a large all-in-one image; add tools through features so the list stays readable.
• Put dependency installation in postCreateCommand and cheap per-start work (starting a local service, printing the port list) in postStartCommand; keep create-time commands idempotent, since prebuilds may run them ahead of time.
• Forward only the ports the application needs, and set remoteUser to a non-root user so files created in the bind-mounted workspace have sane ownership.
• Keep customizations minimal: the formatter, recommended extensions, nothing personal.
• Rebuild the container from scratch in CI on a schedule to catch base-image drift and to prove the configuration still builds.

Pitfalls

A dev container does not replace a lock file: the image pins the toolchain, not the project's dependencies. Where the workspace bind mount is slow (commonly reported for Docker Desktop on macOS and Windows with large trees), the reference's workspaceMount property overrides the default mount, for example with a named volume. Secrets must not be baked into the image or containerEnv; provide them at attach time. Docker-in-Docker inside the container is a feature with its own trade-offs, not a default.