Cloud Native Devcontainer

Production-ready development container with modern tooling for cloud-native and infrastructure development.

What's Inside

Languages: Go, Node.js, Python, Rust (via cargo-binstall), uv, pnpm, aube
Cloud: AWS CLI, Terraform, Kubernetes (kubectl, k9s, k3d, helm, kustomize)
Development: Docker-outside-of-Docker, OpenCode, oy, git, just, mise, direnv, starship, zellij, neovim, lazygit, delta, difftastic
Security: Semgrep, cosign, SLSA verifier, lychee (link checker), Trivy, Syft, sops, age
Linting/formatting: ShellCheck, shfmt, actionlint, taplo, typos, hadolint, yamlfmt
Utilities: ripgrep, fzf, jq, yq, httpie, hurl, btop, restic, rclone

Complete list: See src/wagov_devcontainer/spec.py and src/wagov_devcontainer/deploy.py

Quick Start

VS Code Devcontainer (Recommended)

Create .devcontainer/devcontainer.json:

{
  "name": "My Project",
  "image": "ghcr.io/wagov-dtt/devcontainer-base",
  "features": {
    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
      "moby": false,
      "dockerDashComposeVersion": "none"
    }
  },
  "remoteEnv": {
    "LOCAL_WORKSPACE_FOLDER": "${localWorkspaceFolder}"
  },
  "remoteUser": "vscode"
}

Open in VS Code: Cmd/Ctrl+Shift+P → "Dev Containers: Reopen in Container"

Rootless Docker

For rootless Docker, override the feature's default socket mount to point at your user socket:

{
  "name": "My Project",
  "image": "ghcr.io/wagov-dtt/devcontainer-base",
  "features": {
    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
      "moby": false,
      "dockerDashComposeVersion": "none"
    }
  },
  "mounts": [
    {
      "source": "/run/user/1000/docker.sock",
      "target": "/var/run/docker-host.sock",
      "type": "bind"
    }
  ],
  "remoteUser": "vscode"
}

Replace 1000 with id -u from your host.

Docker bind mounts from inside the devcontainer

Docker commands run against the host daemon, so bind-mount source paths must exist on the host. Use LOCAL_WORKSPACE_FOLDER when invoking Docker:

docker run --rm -v "${LOCAL_WORKSPACE_FOLDER}:/workspace" debian:stable-slim pwd

For projects with Docker Compose files that assume container paths match host paths, mount the workspace at the same absolute path:

{
  "workspaceFolder": "${localWorkspaceFolder}",
  "workspaceMount": "source=${localWorkspaceFolder},target=${localWorkspaceFolder},type=bind"
}

This is not available when using VS Code's Clone Repository in Container Volume flow, because ${localWorkspaceFolder} does not exist there.

Docker CLI

The image still includes Docker CLI/buildx/compose for direct docker run usage outside VS Code Dev Containers:

# Basic usage (mount host Docker socket)
docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --group-add $(stat -c '%g' /var/run/docker.sock) \
  ghcr.io/wagov-dtt/devcontainer-base

# With your projects mounted
docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --group-add $(stat -c '%g' /var/run/docker.sock) \
  -v ~/projects:/workspaces \
  ghcr.io/wagov-dtt/devcontainer-base

Install on Existing System

Works on Debian/Ubuntu, including Ubuntu 26.04. On atomic or other brew-based hosts, the pyinfra deploy can use Homebrew for user-space tooling instead of attempting APT/extrepo or Docker daemon changes.

For direct uvx/pipx run usage, install these first:

• GitHub CLI (gh)
• either uv (uvx) or pipx

To avoid GitHub API rate limits during tool installs, export a token from gh first:

export GITHUB_TOKEN="$(gh auth token)"

# Preferred: run the published package directly
uvx wagov-devcontainer

# Or with pipx
pipx run --spec wagov-devcontainer wagov-devcontainer

# Repo helper script for Debian/Ubuntu, including Ubuntu 26.04
curl -sSL https://raw.githubusercontent.com/wagov-dtt/devcontainer-base/main/install.sh | sh

The helper script also auto-detects GITHUB_TOKEN from gh auth token when gh is installed. On non-APT hosts, use uvx or pipx run directly; the helper script will not try to bootstrap packages there. If brew is on PATH, the deploy installs the needed user-space packages itself and then runs mise install --yes once mise is available.

Use as Template

1. GitHub: Click "Use this template" to create your own repository
2. Codespaces: Works immediately - click "Code" → "Create codespace"
3. Local: Clone and customize as needed

CI/CD Integration

Run tests in the devcontainer for guaranteed consistency:

- name: Run tests in devcontainer
  uses: devcontainers/ci@v0.3
  with:
    imageName: local/devcontainer
    push: never
    runCmd: |
      just test
      mise run lint

See .github/workflows/test-devcontainer.yml for complete example.

How It Works

Architecture

• Base: Debian stable-backports (currently Trixie/13)
• Package Management: APT for system tools, mise for development tools
• Build: Python package (wagov-devcontainer) runs a pyinfra deploy during Docker build or local install
• Docker-outside-of-Docker: Host socket reuse via the upstream Dev Containers feature; Docker CLI/buildx/compose are also pre-installed for plain docker run usage

Tool Sources

Tools are installed from two sources, preferring APT when available:

1. APT via extrepo (preferred) - Signed packages from official repos
   • Docker, GitHub CLI, Terraform, kubectl, mise
2. mise - Cross-platform tools not in APT, or needing version flexibility
   • Languages (Go, Node, Python), k9s, starship
   • npm-backed tools are installed through aube (npm.package_manager = "aube")
   • Cargo-backed tools use cargo-binstall when prebuilt binaries are available

Key Features

• Security: SBOM, signed images, Semgrep in-container
• Performance: Multi-platform builds (amd64/arm64), layer caching
• Flexibility: mise auto-switches tool versions per project
• Supply Chain: Verified packages via extrepo

Adding Tools

Edit src/wagov_devcontainer/spec.py and add to the appropriate mapping:

MISE_TOOLS = {
    # Simple: tool name -> pinned to "latest"
    "pipx:your-tool": "latest",  # or npm:, cargo:, github:user/repo

    # Complex: use structured values for inline TOML tables
    "pipx:tool": {"version": "latest", "extras": "extra", "uvx_args": "--with dep"},
}

MISE_SETTINGS is also structured Python data, and MISE_TOML is rendered from it.

For provisioning behaviour, edit src/wagov_devcontainer/deploy.py. Then rebuild: just build

See CONTRIBUTING.md for contributor guidance.

Optional Cloud CLIs

GCP CLI and Azure CLI are not installed by default (saves ~1 GB). Install them when needed:

# GCP CLI (repo already enabled via extrepo)
sudo apt-get update && sudo apt-get install -y google-cloud-cli

# Azure CLI (repo not available for Trixie, use pipx)
pipx install azure-cli

Development Commands

just              # List all commands
just build        # Build test image
just test         # Test Docker-outside-of-Docker
just dev          # Interactive shell
just lint         # Format and lint Python sources
just clean        # Clean up images

For maintainers:

just publish      # Multi-platform build + push
just shell        # Run published image interactively

Troubleshooting

Contributing

1. Fork and clone the repo
2. Make changes to src/wagov_devcontainer/, Dockerfile, or docs
3. Test: just build && just test && just dev
4. Submit PR with test results

What to contribute:

• New tools or tool updates
• Documentation improvements
• Bug fixes
• Performance optimisations

See CONTRIBUTING.md for contributor guidance and project philosophy.