Modern Cloud Native Devcontainer

A production-ready development container for cloud-native and infrastructure development, built with modern practices and optimised for performance.

🏗️ Architecture

Base: debian:stable-backports - Debian 13 Trixie stable + backports
Docker: Official Docker CE with manual Docker-in-Docker setup
Package Management: Hybrid approach - official Debian packages + mise for specialized tools
Build System: Modern Docker BuildKit with docker bake and optimised caching

🚀 Quick Start

Use as VS Code Devcontainer

Create a .devcontainer/devcontainer.json with the following configuration:

{
	"name": "wagov-dtt devcontainer-base",
	"image": "ghcr.io/wagov-dtt/devcontainer-base",
	"privileged": true,
	"runArgs": [
		"--cgroupns=host"
	],
	"mounts": [
		"source=dind-var-lib-docker,target=/var/lib/docker,type=volume"
	],
	"remoteUser": "vscode"
}

Required settings explained:

• "privileged": true - Enables Docker-in-Docker functionality
• "--cgroupns=host" - Required for proper container networking and k3d/minikube cluster functionality
• "mounts": [...] - Persists Docker data across container rebuilds
• "remoteUser": "vscode" - Sets proper user permissions for VS Code integration

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

Use directly with Docker

# Basic usage
docker run -it --privileged --cgroupns=host \
  --mount source=dind-var-lib-docker,target=/var/lib/docker,type=volume \
  ghcr.io/wagov-dtt/devcontainer-base:latest

# Mount local development folder
docker run -it --privileged --cgroupns=host \
  --mount source=dind-var-lib-docker,target=/var/lib/docker,type=volume \
  --mount type=bind,source=/path/to/your/projects,target=/workspaces \
  ghcr.io/wagov-dtt/devcontainer-base:latest

Project switching: Mount your local dev folder to /workspaces - mise automatically switches tool versions based on each project's mise.toml configuration.

For Image Development

# Core workflow (works locally or in Codespaces)
just build          # Build test image locally with docker bake
just test           # Build and test Docker-in-Docker
just dev            # Interactive development shell
just publish        # Multi-platform build + publish + sign with provenance (requires GITHUB_TOKEN)

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 devcontainer.json as needed

Use in CI/CD

• Simple CI: Use mise GitHub Action with mise.toml for tool management
• Advanced CI: Use full container image for complex workflows requiring Docker-in-Docker

📦 Included Tools

This container uses a hybrid approach: essential tools via Debian packages, specialized tools via mise.

System & Core Tools (Debian packages)

• Docker: Docker CE with BuildKit, compose, and buildx plugins
• Cloud CLIs: Azure CLI, Google Cloud CLI, GitHub CLI
• Infrastructure: Terraform with TFLint & terraform-docs, Helm, ddev
• Development: neovim, fzf, ripgrep, btop, htop, crush
• Build tools: build-essential, ca-certificates, openssh-client
• System utilities: less, jq, unzip, zip, file, rsync, bash-completion
• Network tools: iputils-ping, dnsutils, net-tools, procps, lsof
• File management: restic, rclone, ugrep

Language Runtimes & Development (mise)

• Languages: Go, Node.js, Python
• Package Managers: pnpm, uv, pipx
• Build Tools: just, yq

Cloud & Kubernetes (mise)

• AWS: AWS CLI, AWS SAM
• Kubernetes: kubectl, k9s, k3d, kustomize
• Infrastructure: TFLint, terraform-docs
• Security: Trivy, Vault

Productivity & Terminal (mise)

• Terminal: Zellij, starship, zoxide, eza, direnv, tldr
• Git: LazyGit
• Documentation: mdbook, Lychee, rumdl
• Testing: Hurl, HTTPie, Semgrep
• Package Managers: @devcontainers/cli, cargo-binstall
• Code Analysis: scc
• Local Development: LocalStack

Current tools: See mise.toml and Dockerfile for complete, up-to-date lists.

Learning CLI tools: Use tldr <command> to get practical examples for any CLI tool - much faster than reading full man pages.

🔧 Configuration

Commands

# Development
just build           # Build test image locally with docker bake
just test            # Test Docker-in-Docker functionality
just dev             # Interactive development shell (build + test + shell)
just scan            # Security scan with Trivy
just clean           # Clean up images and volumes

# Publishing (maintainers)  
just publish         # Multi-platform build + push + sign with provenance
just shell           # Run published image interactively

Customization

Add/remove tools: Edit mise.toml

[tools]
your-tool = "latest"

Custom packages: Add to Dockerfile APT install section

Build configuration: Modify docker-bake.hcl for advanced build options

VS Code settings: Add to devcontainer.json customizations

Environment variables: Set in devcontainer.json or during runtime

🏭 Production Features

Modern Docker Practices

• Docker Bake: Declarative multi-platform builds with HCL functions and native manifest creation
• Supply Chain Security: Comprehensive SBOM generation and enhanced provenance attestations (mode=max)
• BuildKit: Advanced build features with squashed layers and zstd compression
• Secrets: Secure GITHUB_TOKEN handling for private repository access
• Cache mounts: Persistent cache for APT packages and mise downloads

Security & Compliance

• Supply chain attestations: Automated SBOM and detailed provenance generation for every build
• Official packages: Debian repositories where available
• Signed packages: GPG verification for all external repos
• Trivy scanning: Automated vulnerability detection
• Minimal attack surface: No unnecessary services

Performance Optimisations

• Native builds: AMD64/ARM64 compile on matching hardware, no QEMU emulation
• Cache mounts: APT packages and mise downloads persist across builds
• Architecture-specific caching: Separate cache scopes prevent conflicts
• Single APT transaction: Merged system upgrade and package installation
• Volume persistence: Docker-in-Docker storage optimisation
• Smart retries: Resilient network operations for mise tool installation

🔐 Docker-in-Docker

Features

• Privileged mode: Full Docker daemon access
• Volume persistence: Shared Docker storage across rebuilds
• Automatic startup: Docker daemon starts with container
• Health checks: Ensures Docker is ready before use

Security Considerations

• Uses official Docker CE
• No unnecessary network exposure
• User-scoped permissions via docker group

🎯 Use Cases

Cloud Development

• Multi-cloud CLI tools (AWS, Azure, GCP)
• Infrastructure as Code (Terraform with linting & documentation)
• Container orchestration (Kubernetes)
• Serverless applications (AWS SAM)

DevOps & SRE

• Container builds and testing
• Security scanning (Trivy) with automated provenance
• Backup solutions (Restic, rclone)
• Monitoring and debugging tools

Full-Stack Development

• Multiple runtime support (Go, Node.js, Python)
• Modern package managers (pnpm, uv)
• Documentation tools (mdbook, Lychee)
• API testing (Hurl, HTTPie)

🤝 Contributing

1. Issues: Report bugs or request features
2. Pull Requests: Improve tools, documentation, or performance
3. Testing: Verify compatibility across environments
4. Documentation: Help others understand and use the project

Development Workflow

# Make changes to Dockerfile, mise.toml, or docker-bake.hcl
just build        # Build test image locally with docker bake
just test         # Test Docker-in-Docker functionality
just dev          # Interactive development shell
just scan         # Security scan with Trivy
# Submit PR with test results

Troubleshooting

• Docker issues: Ensure privileged: true and volume mount are configured
• Tool conflicts: Run mise install to refresh tool installations
• Build cache: Use just clean to reset Docker build cache if needed

🙏 Acknowledgments

• Debian - Stable base operating system
• mise - Polyglot tool version manager
• just - Command runner
• Devcontainers - Development container specification
• Docker - Container platform and BuildKit