Dev Containers

What it is

Dev Containers is an open specification for defining complete development environments in Docker containers. A devcontainer.json file describes everything needed: base image, tools, editor extensions, environment variables, and network configuration. Any developer can open the project and get an identical environment in minutes, without installing dependencies locally.

The specification goes beyond a simple Dockerfile. It defines how the editor should behave inside the container, which ports to expose, how to handle source code, and what commands to run after creating the container. It's infrastructure as code applied to the development environment.

Devcontainers eliminate onboarding friction and ensure all developers work with the same tool versions, reducing environment-related bugs and improving developer experience.

Complete configuration

A real devcontainer.json for a Node.js project with database:

{
  "name": "Full Stack App",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "features": {
    "ghcr.io/devcontainers/features/aws-cli:1": {
      "version": "latest"
    },
    "ghcr.io/devcontainers/features/docker-in-docker:2": {
      "version": "latest",
      "dockerDashComposeVersion": "v2"
    },
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-vscode.vscode-typescript-next",
        "bradlc.vscode-tailwindcss",
        "ms-vscode.vscode-json",
        "esbenp.prettier-vscode"
      ],
      "settings": {
        "typescript.preferences.importModuleSpecifier": "relative",
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "esbenp.prettier-vscode"
      }
    }
  },
  "forwardPorts": [3000, 5432],
  "portsAttributes": {
    "3000": {
      "label": "Application",
      "onAutoForward": "notify"
    }
  },
  "postCreateCommand": "npm install && npm run db:migrate",
  "postStartCommand": "npm run dev",
  "remoteUser": "node",
  "mounts": [
    "source=${localWorkspaceFolder}/.aws,target=/home/node/.aws,type=bind,consistency=cached"
  ]
}

Multi-service setup

For applications with multiple services, use Docker Compose:

# docker-compose.yml
version: '3.8'
services:
  app:
    build:
      context: .
      dockerfile: .devcontainer/Dockerfile
    volumes:
      - ../..:/workspaces:cached
    command: sleep infinity
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/myapp
    depends_on:
      - db
      - redis
 
  db:
    image: postgres:15
    restart: unless-stopped
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: myapp
 
  redis:
    image: redis:7-alpine
    restart: unless-stopped
 
volumes:
  postgres-data:

GPU support

For AI or machine learning development:

{
  "name": "ML Development",
  "image": "mcr.microsoft.com/devcontainers/python:3.11",
  "features": {
    "ghcr.io/devcontainers/features/nvidia-cuda:1": {
      "installCudnn": true
    }
  },
  "runArgs": ["--gpus", "all"],
  "postCreateCommand": "pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118"
}

CI/CD integration

Devcontainers can run in CI/CD to ensure parity between development and testing:

# .github/workflows/test.yml
name: Test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: devcontainers/ci@v0.3
        with:
          runCmd: npm test

Tool comparison

Available features

The features ecosystem allows adding tools without modifying the base image:

• Languages: Node.js, Python, Go, Rust, Java, .NET
• Cloud: AWS CLI, Azure CLI, Google Cloud CLI, Terraform
• Tools: Git, GitHub CLI, Docker-in-Docker, Kubernetes CLI
• Databases: PostgreSQL, MySQL, MongoDB, Redis

Each feature is versioned independently and can be configured with specific options.

Why it matters

Devcontainers solve one of the most expensive problems in engineering: environment inconsistency. A senior developer can lose days setting up a complex project, and environment-related bugs consume valuable debugging time.

By defining the environment as code, devcontainers guarantee reproducibility and reduce onboarding time from days to minutes. This is especially critical in distributed teams where each developer has a different setup. The initial investment in configuring devcontainers pays off quickly with reduced friction and environment-related bugs.

References

• Development containers — Dev Containers, 2024. Official specification and documentation.
• Development Container Specification — Dev Containers, 2024. Complete technical specification of the format.
• Features — Dev Containers, 2024. Official catalog of available features.
• Developing inside a Container — Microsoft, 2024. Official VS Code guide for devcontainers.
• Adding a dev container configuration to your repository - GitHub Docs — GitHub, 2024. Configuration for GitHub Codespaces.
• Maximizing Developer Effectiveness — Martin Fowler, 2021. Analysis of factors impacting developer productivity.
• GitHub's Engineering Team has moved to Codespaces - The GitHub Blog — GitHub, 2021. Internal adoption case study.