Dev Container Configuration

Overview

This skill provides comprehensive guidance for working with devcontainer.json files – the configuration files that define Development Containers. It covers all configuration scenarios (image-based, Dockerfile-based, and Docker Compose), property usage, common patterns, and validation.

Quick Start

Determine Configuration Type

Choose the appropriate base configuration:

1. Image-based – Use an existing container image:

• Best for: Standard development environments, quick setup
• Template: assets/basic-image.json
• Required property: image

2. Dockerfile-based – Build from a custom Dockerfile:

• Best for: Custom environments, specific tool versions
• Template: assets/dockerfile-based.json
• Required property: build.dockerfile

3. Docker Compose – Multi-container environments:

• Best for: Apps with databases, microservices
• Template: assets/docker-compose.json
• Required properties: dockerComposeFile, service

Basic Workflow

1. Start with template: Copy the appropriate template from assets/
2. Configure basics: Set name, add features, configure customizations
3. Add lifecycle scripts: Set postCreateCommand, postStartCommand, etc.
4. Configure ports: Add forwardPorts and portsAttributes as needed
5. Validate: Run scripts/validate.py to check for issues

Common Configuration Tasks

Adding Dev Container Features

Features extend container functionality. Add them using the features property:

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

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

Configuring Environment Variables

Use containerEnv for static, container-wide variables:

{
  "containerEnv": {
    "NODE_ENV": "development",
    "API_URL": "http://localhost:3000"
  }
}

Use remoteEnv for client-specific variables that may change:

{
  "remoteEnv": {
    "LOCAL_USER": "${localEnv:USER}"
  }
}

Setting Up Lifecycle Scripts

Configure commands that run at different stages:

{
  "onCreateCommand": "npm ci",
  "updateContentCommand": "npm install",
  "postCreateCommand": "npm run build",
  "postStartCommand": "npm run dev"
}

Command formats:

• String: Runs in shell, supports && and pipes
• Array: Direct execution without shell
• Object: Parallel execution of multiple commands

Port Forwarding

Forward ports with custom behavior:

{
  "forwardPorts": [3000, 5432],
  "portsAttributes": {
    "3000": {
      "label": "Application",
      "onAutoForward": "openBrowser"
    },
    "5432": {
      "label": "Database",
      "onAutoForward": "silent"
    }
  }
}

VS Code Extensions

Add extensions via customizations:

{
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ]
    }
  }
}

Advanced Configuration

Security and Debugging

For debugging languages like C++, Go, Rust:

{
  "capAdd": ["SYS_PTRACE"],
  "securityOpt": ["seccomp=unconfined"]
}

For Docker-in-Docker:

{
  "features": {
    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
  },
  "privileged": true
}

Custom Mounts

Mount additional directories or volumes:

{
  "mounts": [
    {
      "source": "${localEnv:HOME}/.ssh",
      "target": "/home/vscode/.ssh",
      "type": "bind"
    },
    {
      "source": "project-cache",
      "target": "/workspace/.cache",
      "type": "volume"
    }
  ]
}

User Configuration

Control which user runs commands:

{
  "containerUser": "vscode",
  "remoteUser": "vscode",
  "updateRemoteUserUID": true
}

• containerUser: User for all container operations
• remoteUser: User for dev tools/terminals
• updateRemoteUserUID: Match local user UID/GID on Linux

Validation

Use the validation script to check configurations:

python scripts/validate.py /path/to/devcontainer.json

The validator checks for:

• Required properties based on scenario
• Proper lifecycle script formats
• Valid port configurations
• Correct variable syntax
• Common configuration issues

Example output:

============================================================
Validation Results for: devcontainer.json
============================================================

❌ ERRORS:
  - Must specify one of: 'image', 'build.dockerfile', or 'dockerComposeFile'

⚠️  WARNINGS:
  - Missing 'name' property - recommended for UI display

❌ Validation failed with 1 error(s)

Reference Documentation

For detailed property information:

• references/properties.md: Complete reference of all devcontainer.json properties
• references/patterns.md: Real-world examples and common patterns

Use these references when:

• Looking up specific property syntax
• Understanding property interactions
• Finding examples for specific scenarios
• Learning about advanced features

Variables

Available variables for use in string values:

• ${localEnv:VAR_NAME} – Environment variable from host machine
• ${containerEnv:VAR_NAME} – Environment variable from container
• ${localWorkspaceFolder} – Local path to workspace
• ${containerWorkspaceFolder} – Container path to workspace
• ${localWorkspaceFolderBasename} – Workspace folder name
• ${devcontainerId} – Unique container identifier

Default values: ${localEnv:VAR:default_value}

Troubleshooting

Container won’t start

• Check that required properties are present (image, build.dockerfile, or dockerComposeFile)
• Validate JSON syntax
• Check that referenced files (Dockerfile, docker-compose.yml) exist

Permission issues

• Set updateRemoteUserUID: true on Linux
• Configure containerUser and remoteUser appropriately

Ports not forwarding

• Ensure application listens on 0.0.0.0 not just localhost
• Check forwardPorts configuration
• Review portsAttributes settings

Features not installing

• Verify feature IDs are correct
• Check network connectivity
• Use overrideFeatureInstallOrder if dependencies exist

Lifecycle scripts failing

• Check script syntax (string vs array vs object)
• Review script output in dev container log
• Ensure required tools are available in container
• Remember: If a script fails, subsequent scripts won’t run