Dev Containers What · Why · When · How — with production-ready samples

┌─ Your Machine (host) ──────────────────────────────────────────┐
│                                                                 │
│   VS Code UI ←──── local rendering ────────────────────────┐  │
│         ↕  (extension protocol)                             │  │
│   ┌─ Docker Container ─────────────────────────────────┐   │  │
│   │                                                     │   │  │
│   │   VS Code Server (runs inside container)            │   │  │
│   │   ├─ Language servers (LSP)                         │   │  │
│   │   ├─ Debugger                                       │   │  │
│   │   ├─ Terminal (bash/zsh inside container)           │   │  │
│   │   └─ Extensions (installed inside container)        │   │  │
│   │                                                     │   │  │
│   │   /workspaces/my-project ←── bind mount ──────────────── │  │
│   │   Node 22, Python 3.12, .NET 8, Go 1.23, etc.      │   │  │
│   │   git, gh CLI, custom tools                         │   │  │
│   └─────────────────────────────────────────────────────┘   │  │
│                                                                 │
│   Source files stay on host disk — edited locally by VS Code  │
└─────────────────────────────────────────────────────────────────┘

{
  "name": "My Project Dev",              // Display name in VS Code UI

  // ── IMAGE / BUILD SOURCE (pick one) ─────────────────
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  // OR
  "build": {
    "dockerfile": "Dockerfile",
    "context": "..",
    "args": { "VARIANT": "22-bookworm" }
  },
  // OR for Docker Compose
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "runServices": ["db", "redis"],

  // ── FEATURES ────────────────────────────────────────
  "features": {
    "ghcr.io/devcontainers/features/node:1": { "version": "22" },
    "ghcr.io/devcontainers/features/git:1": {},
    "ghcr.io/devcontainers/features/github-cli:1": {},
    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
  },

  // ── WORKSPACE ────────────────────────────────────────
  "workspaceFolder": "/workspaces/my-project",

  // ── PORT FORWARDING ──────────────────────────────────
  "forwardPorts": [3000, 5432, 6379],
  "portsAttributes": {
    "3000": { "label": "App", "onAutoForward": "openBrowser" },
    "5432": { "label": "PostgreSQL", "onAutoForward": "silent" }
  },

  // ── ENVIRONMENT ──────────────────────────────────────
  "containerEnv": {
    "NODE_ENV": "development",
    "DATABASE_URL": "postgresql://user:pass@db:5432/mydb"
  },
  "remoteEnv": {
    "LOCAL_WORKSPACE": "${localWorkspaceFolder}"  // host path
  },

  // ── DECLARATIVE SECRETS (spec addition) ──────────────
  // Declares required secrets WITHOUT storing values in the file.
  // Supporting tools (Codespaces, CLI) prompt for or inject these.
  "secrets": {
    "OPENAI_API_KEY": { "description": "Key for local LLM calls in tests" },
    "DATABASE_PASSWORD": { "description": "Seed DB password, not the prod one" }
  },

  // ── USER ─────────────────────────────────────────────
  "remoteUser": "node",        // run VS Code Server as this user
  "updateRemoteUserUID": true,  // sync UID/GID with host (Linux)

  // ── MOUNTS ───────────────────────────────────────────
  "mounts": [
    "source=${localEnv:HOME}/.ssh,target=/home/node/.ssh,type=bind,readonly",
    "source=my-volume,target=/data,type=volume"
  ],

  // ── LIFECYCLE SCRIPTS ────────────────────────────────
  "onCreateCommand": "npm install",
  "updateContentCommand": "npm install",
  "postCreateCommand": "bash .devcontainer/scripts/post-create.sh",
  "postStartCommand": "git config core.autocrlf false",
  "postAttachCommand": { // parallel execution (object form)
    "info": "echo 'Container ready!'",
    "check": "node --version"
  },

  // ── VS CODE CUSTOMIZATION ────────────────────────────
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ms-azuretools.vscode-docker"
      ],
      "settings": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "terminal.integrated.defaultProfile.linux": "bash"
      }
    }
  },

  // ── CONTAINER OPTIONS ────────────────────────────────
  "runArgs": ["--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined"],
  "hostRequirements": { "memory": "4gb", "cpus": 2 }
}