Development Containers Expert

Expert guidance for working with Development Containers (devcontainers) - a standardized way to create fully-featured, containerized development environments.

When to Use This Skill

Activate this skill when:

• Creating or configuring devcontainer.json files
• Setting up containerized development environments in VS Code
• Working with dev container Templates or Features
• Troubleshooting devcontainer issues
• Integrating development containers with Docker or Docker Compose
• User mentions: devcontainers, dev containers, devcontainer.json, VS Code containers, containerized development, or development environment setup

What Are Development Containers?

A development container (dev container) is a running Docker container with a well-defined tool/runtime stack and its prerequisites. The configuration is defined in a devcontainer.json file that tells VS Code (or other supporting tools) how to access or create a development container.

Key Benefits:

• Consistency: Same environment for all developers
• Repeatability: Quickly recreate environments
• Isolation: Separate tools/libraries per project
• Onboarding: New developers get productive faster
• CI/CD Integration: Same environment for local dev and testing

The Specification: Dev containers follow the open Development Containers Specification maintained by the devcontainers community.

Prerequisites

Required Software

1. Docker

   • Windows: Docker Desktop 2.0+ (Windows 10 Pro/Enterprise or Windows 10 Home 2004+ with WSL 2)
   • macOS: Docker Desktop 2.0+
   • Linux: Docker CE/EE 18.06+ and Docker Compose 1.21+

2. VS Code

   • Visual Studio Code or VS Code Insiders
   • Dev Containers extension (ms-vscode-remote.remote-containers)

3. System Resources

   • Minimum: 1 GB RAM
   • Recommended: 2 GB RAM and 2-core CPU

Installation Steps

Windows/macOS:

1. Install Docker Desktop from https://www.docker.com/products/docker-desktop
2. For Windows WSL 2: Enable "Use the WSL 2 based engine" in Docker Desktop settings
3. Install VS Code from https://code.visualstudio.com/
4. Install the Dev Containers extension from the VS Code Extensions marketplace

Linux:

1. Install Docker CE/EE following official instructions for your distribution
2. Add your user to the docker group: sudo usermod -aG docker $USER
3. Sign out and back in for changes to take effect
4. Install VS Code
5. Install the Dev Containers extension

Creating a devcontainer.json File

The devcontainer.json file is the core configuration for your dev container. It can be placed in one of two locations:

• .devcontainer/devcontainer.json (recommended for complex setups)
• .devcontainer.json (root of project)

Quick Start: Using a Template

The easiest way to create a dev container is using a pre-built Template:

1. Open Command Palette in VS Code: F1 or Cmd/Ctrl+Shift+P
2. Run: Dev Containers: Add Dev Container Configuration Files...
3. Select a Template based on your tech stack (e.g., Node.js, Python, Go, Java)
4. Customize with Features (optional) - add tools like Git, GitHub CLI, Docker-in-Docker
5. Reopen in Container: Run Dev Containers: Reopen in Container

VS Code will build the container and reopen your workspace inside it.

Basic devcontainer.json Structure

Minimal Example (Using Pre-built Image):

{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "forwardPorts": [3000],
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ]
    }
  }
}

Using a Dockerfile:

{
  "name": "My Custom Container",
  "build": {
    "dockerfile": "Dockerfile",
    "context": "..",
    "args": {
      "VARIANT": "18"
    }
  },
  "forwardPorts": [3000, 5000],
  "postCreateCommand": "npm install",
  "customizations": {
    "vscode": {
      "settings": {
        "terminal.integrated.defaultProfile.linux": "bash"
      },
      "extensions": ["dbaeumer.vscode-eslint"]
    }
  }
}

Using Docker Compose:

{
  "name": "My Multi-Container App",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "forwardPorts": [3000],
  "postCreateCommand": "npm install",
  "customizations": {
    "vscode": {
      "extensions": ["dbaeumer.vscode-eslint"]
    }
  }
}

Ready-to-Use Templates

For quick starts, this skill includes practical, copy-paste devcontainer.json templates in assets/templates/:

• basic-node.json - Simple Node.js/TypeScript starter
• python-with-features.json - Python with Features demonstration
• docker-compose.json - Multi-service full-stack app
• advanced-lifecycle.json - Complex lifecycle patterns
• monorepo-polyglot.json - Multi-language monorepo
• security-hardened.json - Security best practices
• dockerfile-multistage.json - Custom Dockerfile with multi-stage builds

Each template is fully commented and demonstrates different patterns. For detailed template descriptions, selection guidance, and usage instructions, see references/TEMPLATES_GUIDE.md.

Key Configuration Properties

Container Definition:

• name: Display name for the container
• image: Pre-built Docker image to use
• build: Build configuration (dockerfile, context, args, target, cacheFrom, options)
• dockerComposeFile: Path to docker-compose.yml file
• service: Docker Compose service name to connect to

Environment Setup:

• workspaceFolder: Path where workspace is mounted (default: /workspaces/<project-name>)
• workspaceMount: Custom workspace mount configuration
• mounts: Additional volume/bind mounts
• containerEnv: Environment variables for the container
• containerUser: User for starting the container (default: image default)
• remoteUser: User to run as inside container (default: root or image default)
• remoteEnv: Environment variables for remote processes and IDE server
• updateRemoteUserUID: Update container user's UID/GID to match local user (Linux only)

Port Forwarding:

• forwardPorts: Array of ports to forward (e.g., [3000, 8080])
• appPort: Application ports exposed by container (deprecated in favor of forwardPorts)
• portsAttributes: Configure port labels, protocols, auto-forward behavior, and elevation
• otherPortsAttributes: Default properties for ports not explicitly configured

Lifecycle Scripts:

• initializeCommand: Runs locally before anything else
• onCreateCommand: Runs once when container is created
• updateContentCommand: Runs when container config changes
• postCreateCommand: Runs after container creation (often used for npm install, pip install)
• postStartCommand: Runs every time the container starts
• postAttachCommand: Runs every time you attach to the container
• waitFor: Which command to wait for before starting UI (default: updateContentCommand)

Advanced Container Options:

• runArgs: Additional Docker run arguments
• init: Pass --init flag for proper signal handling
• privileged: Run container in privileged mode
• capAdd: Docker capabilities to add
• securityOpt: Docker security options
• overrideCommand: Override the default command from the image
• shutdownAction: Action when disconnecting (none or stopContainer/stopCompose)

Features and Environment:

• features: Features to add to the container
• overrideFeatureInstallOrder: Control the order Features are installed
• userEnvProbe: How to load user environment (none, loginShell, loginInteractiveShell, interactiveShell)

Host Requirements:

• hostRequirements: Minimum host hardware (cpus, memory, storage, gpu)

Security and Secrets:

• secrets: Recommended secrets with descriptions and documentation URLs

VS Code Customization:

• customizations.vscode.extensions: Extensions to install in the container
• customizations.vscode.settings: VS Code settings for the container
• customizations: Tool-specific customizations for other editors/tools

Working with Dev Container Features

Features are self-contained, shareable units of installation code that add tools, runtimes, or libraries to your container.

Adding Features

Method 1: During Setup When running Dev Containers: Add Dev Container Configuration Files..., you'll be prompted to select Features.

Method 2: Add to Existing Config

1. Open Command Palette: F1
2. Run: Dev Containers: Configure Container Features
3. Select Features to add

Method 3: Edit devcontainer.json Directly

{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "20"
    },
    "ghcr.io/devcontainers/features/git:1": {
      "version": "latest"
    },
    "ghcr.io/devcontainers/features/github-cli:1": {},
    "ghcr.io/devcontainers/features/docker-in-docker:2": {
      "version": "latest",
      "moby": true
    }
  }
}

Popular Features

Browse all at https://containers.dev/features:

• node, python, go, rust, java, dotnet - Language runtimes
• git, github-cli, azure-cli, aws-cli - CLI tools
• docker-in-docker, kubectl-helm-minikube - Container/K8s tools
• common-utils - Essential utilities (zsh, oh-my-zsh, etc.)

Pinning Feature Versions

Features follow semantic versioning. You can pin to specific versions:

"features": {
  "ghcr.io/devcontainers/features/node:1": {},           // Latest v1.x.x
  "ghcr.io/devcontainers/features/python:1.0": {},       // Latest v1.0.x
  "ghcr.io/devcontainers/features/go:1.0.0": {}          // Exact version 1.0.0
}

Creating Custom Features

You can create your own Features using the feature-starter template. Each Feature is a folder with:

• devcontainer-feature.json - Metadata and options
• install.sh - Installation script

Controlling Feature Installation Order

By default, Features are installed in an implementation-defined order. To control this:

{
  "features": {
    "ghcr.io/devcontainers/features/common-utils:1": {},
    "ghcr.io/devcontainers/features/node:1": {},
    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
  },
  "overrideFeatureInstallOrder": [
    "ghcr.io/devcontainers/features/common-utils",
    "ghcr.io/devcontainers/features/node",
    "ghcr.io/devcontainers/features/docker-in-docker"
  ]
}

Complete Property Reference

For comprehensive documentation of all devcontainer.json properties with detailed examples, see references/JSON_SCHEMA_REFERENCE.md.

This reference covers:

• All general, container source, and lifecycle properties
• Advanced port configuration and attributes
• Environment variables, user configuration, and variable substitution
• Host requirements (CPU, memory, storage, GPU)
• Security options, secrets management, and container runtime settings
• Build configuration, Docker Compose options, and tool customizations

Common Workflows

Open Local Project in Container:

1. Open project in VS Code
2. Run: Dev Containers: Reopen in Container (F1)
3. Select Template if no devcontainer.json exists
4. VS Code builds and reopens in container

Clone Repository in Container Volume (better performance on Windows/macOS):

1. Run: Dev Containers: Clone Repository in Container Volume...
2. Enter Git URL or select from GitHub
3. Choose Template if needed

Open GitHub PR:

1. Run: Dev Containers: Clone Repository in Container Volume...
2. Paste GitHub PR URL
3. VS Code opens PR with GitHub Pull Requests extension

Rebuild Container (after config changes):

• Dev Containers: Rebuild Container
• OR Dev Containers: Rebuild Container Without Cache (full rebuild)

Attach to Running Container:

1. Run: Dev Containers: Attach to Running Container...
2. Select container from list

Advanced Configuration

Monorepos: Multiple Devcontainers

Important Limitation: Multi-root workspaces (.code-workspace files) open all folders in the same container. To use different containers per package, open each folder separately.

Pattern 1: Separate Package Containers (different tech stacks)

monorepo/
├── apps/
│   ├── frontend/.devcontainer/devcontainer.json
│   └── backend/.devcontainer/devcontainer.json

Frontend (.devcontainer/devcontainer.json):

{
  "name": "Frontend",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "workspaceFolder": "/workspaces/monorepo/apps/frontend",
  "workspaceMount": "source=${localWorkspaceFolder}/../..,target=/workspaces/monorepo,type=bind"
}

Workflow:

• Single package: Right-click frontend/ → "Open Folder in Container"
• Multiple packages: Open separate VS Code windows, one per package

Pattern 2: Unified Polyglot Container (all tools in one)

{
  "name": "Monorepo All",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {"version": "20"},
    "ghcr.io/devcontainers/features/python:1": {"version": "3.11"},
    "ghcr.io/devcontainers/features/go:1": {}
  }
}

Pattern 3: Docker Compose Multi-Container (services in separate containers)

Use Docker Compose when packages need to run simultaneously (frontend + backend + db):

services:
  frontend:
    build: ./apps/frontend
    volumes: [".:/workspace:cached"]
  backend:
    build: ./apps/backend
    volumes: [".:/workspace:cached"]
  db:
    image: postgres:14

{
  "name": "Monorepo",
  "dockerComposeFile": "docker-compose.yml",
  "service": "frontend",
  "workspaceFolder": "/workspace"
}

Choose "frontend" or "backend" as primary service. Access other containers via docker exec or attach in separate windows.

Advanced Topics

For in-depth coverage of advanced scenarios, see the references/ directory:

• Templates Guide - Detailed template descriptions and selection guidance
• JSON Schema Complete Reference - Comprehensive documentation of all devcontainer.json properties
• Pre-building Images - Image caching, CI/CD workflows, supply-chain security
• Kubernetes Integration - Attach to K8s pods, cluster development
• Networking Fundamentals - Docker network modes, port forwarding, DNS, proxies
• Advanced Networking - VPN, network security, service mesh, load balancing
• Volume Performance - Optimize disk performance on Windows/macOS
• Container-in-Container - Docker-in-Docker for CI/CD testing
• Security Hardening - Non-root users, secrets management, capabilities
• Dotfiles & Personalization - Shell customization, tool configuration
• Recovery & Debugging - Fix build failures, inspect containers

Advanced Configuration (Quick Reference)

Using Docker Compose

docker-compose.yml:

services:
  app:
    build: .
    volumes:
      - .:/workspace:cached
    command: sleep infinity
  db:
    image: postgres:14
    environment:
      POSTGRES_PASSWORD: example

devcontainer.json:

{
  "name": "App with Database",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "postCreateCommand": "npm install"
}

Non-Root User (See SECURITY.md)

{
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "remoteUser": "node"
}

Custom Mounts and Environment (See SECURITY.md)

{
  "image": "mcr.microsoft.com/devcontainers/python:3.11",
  "mounts": [
    "source=${localEnv:HOME}/.ssh,target=/home/node/.ssh,readonly,type=bind"
  ],
  "containerEnv": {
    "DATABASE_URL": "postgresql://localhost/mydb"
  }
}

Troubleshooting (Quick Reference)

For comprehensive debugging guides, see references/RECOVERY_DEBUGGING.md.

Common Issues:

• Docker Not Running: Check docker ps works. On Linux: sudo systemctl status docker
• Port Already in Use: Find process with lsof -i :<port> (macOS/Linux) or netstat -ano | findstr :<port> (Windows)
• Slow Performance: See VOLUME_PERFORMANCE.md for optimization strategies
• Build Failures: Use Dev Containers: Reopen in Recovery Container to debug. See RECOVERY_DEBUGGING.md
• Permission Errors: Set remoteUser or see SECURITY.md for non-root configuration

Best Practices

1. Version Control - Commit .devcontainer/ so all developers use the same environment
2. Use Official Images - Start with mcr.microsoft.com/devcontainers/ for reliability
3. Pin Versions - Lock Feature and base image versions for reproducibility
4. Security - Run as non-root, avoid committing secrets. See SECURITY.md
5. Performance - Use volume mounts on Windows/macOS. See VOLUME_PERFORMANCE.md
6. Test Regularly - Ensure new team members can build containers from scratch
7. Document - Add comments explaining custom configurations

Pre-building and CI/CD

Pre-building images improves startup time and enables CI/CD integration. See references/PREBUILDING.md for comprehensive guides.

Quick Example (GitHub Actions):

name: CI
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: devcontainers/[email protected]
        with:
          imageName: ghcr.io/${{ github.repository }}-devcontainer
          cacheFrom: ghcr.io/${{ github.repository }}-devcontainer
          push: always
          runCmd: npm test
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Resources

• Specification: https://containers.dev/
• VS Code Docs: https://code.visualstudio.com/docs/devcontainers/containers
• Templates: https://containers.dev/templates
• Features: https://containers.dev/features
• GitHub Org: https://github.com/devcontainers
• CLI Reference: https://github.com/devcontainers/cli
• Docker Images: https://github.com/devcontainers/images

Quick Reference

VS Code Commands (open with F1 or Cmd/Ctrl+Shift+P):

• Dev Containers: Reopen in Container
• Dev Containers: Rebuild Container
• Dev Containers: Add Dev Container Configuration Files...
• Dev Containers: Configure Container Features
• Dev Containers: Clone Repository in Container Volume...
• Dev Containers: Attach to Running Container...
• Dev Containers: Show Container Log

Key Configuration Locations:

• .devcontainer/devcontainer.json (recommended)
• .devcontainer.json (alternative)
• Dockerfile: .devcontainer/Dockerfile
• Docker Compose: .devcontainer/docker-compose.yml