Development Container

Behaviour#

The development container is responsible for the environment; the repository’s commands only use it. Developers are not expected to run a separate bootstrap step to install tools after the container is built — if a tool is needed, the container provides it.

The definition is layered. A small base image sets the operating system and primary runtime. Devcontainer features add reusable capabilities on top. The Devcontainer Lifecycle adds the last, repository-specific layer.

Features first#

A devcontainer feature is the preferred way to install a common toolchain, configure a runtime dependency, or expose a development service. When a suitable upstream feature exists, it is used instead of re-implementing the install in a lifecycle script or the Dockerfile.

When no upstream feature fits, or organisation-specific behaviour is required, a local feature may be developed under ./features. It stays generic enough to be extracted and reused by other repositories later. Workspace initialisation, shell customisation, and other repository-specific behaviour stay out of features and belong in lifecycle scripts.

Tool versions may come from shared metadata such as .tool-versions, or be pinned directly in devcontainer or CI configuration. Where consistency matters, the pins are shared or coordinated.

Examples#

Every lifecycle command in this repository delegates to the same runner, and toolchains arrive as features:

{
  "build": { "dockerfile": "Dockerfile" },
  "initializeCommand": "bash .devcontainer/lifecycle/run-parts.sh initialize",
  "postStartCommand": "bash .devcontainer/lifecycle/run-parts.sh post-start",
  "features": {
    "ghcr.io/devcontainers/features/aws-cli:1": {},
    "ghcr.io/devcontainers/features/terraform:1": {},
    "ghcr.io/devcontainers/features/hugo:1": {},
    "ghcr.io/devcontainers/features/docker-in-docker:2": { "moby": true }
  }
}

The environment is driven entirely from the Dev Containers CLI, so any editor or automation surface can wrap the same commands:

devcontainer up --workspace-folder .                  # Build and start
devcontainer exec --workspace-folder . make doctor    # Verify the environment
devcontainer exec --workspace-folder . make validate  # Run project validation
devcontainer build --workspace-folder .               # Prebuild or warm the cache

make doctor is the Environment Doctor : it reports what the container was expected to provide and what is missing.