Devcontainer Diagnostic

Diagnose devcontainer and Docker development environment problems. Help create reproducible, fast-starting development environments that work consistently across VS Code, GitHub Codespaces, and team members.

When to Use This Skill

Use this skill when:

• Setting up a new devcontainer

• Container startup is too slow

• Configuration errors or conflicts

• Different behavior in VS Code vs Codespaces

• Multi-service development environment needed

Do NOT use this skill when:

• Writing application code

• Deploying to production

• Configuring CI/CD pipelines

Core Principle

Development containers should provide instant productivity. Every configuration choice affects startup time, reproducibility, and team onboarding. Make these trade-offs explicit.

Diagnostic States

DV0: No Devcontainer Strategy

Symptoms: Manual setup, "check the README", works on one machine fails on others

Interventions:

• Start with pre-built devcontainer base image

• Use assets/devcontainer-simple.md template

DV1: Slow Container Startup

Symptoms: 5+ minute startup, heavy postCreateCommand, avoiding rebuilds

Key Questions:

• How long does startup actually take?

• What's in postCreateCommand?

• Are you using prebuilds?

Interventions:

• Move npm install/pip install to Dockerfile (cached)

• Use mcr.microsoft.com/devcontainers/* base images

• Configure prebuilds for team repos

• Run scripts/analyze-devcontainer.ts

DV2: Configuration Problems

Symptoms: JSON errors, VS Code won't connect, features conflicting

Checklist:

• devcontainer.json passes JSON validation

• Using only ONE of: image, build.dockerfile, dockerComposeFile

• Features are compatible and ordered correctly

• Extensions use correct publisher.extension-name format

DV3: Environment Parity Issues

Symptoms: Works in VS Code, fails in Codespaces (or vice versa)

Common Issues:

Issue Local VS Code Codespaces

Docker socket Usually available Docker-in-Docker needed

Secrets .env files work Use Codespaces secrets

File watching Native May need polling

DV4: Multi-Service Complexity

Symptoms: Need database/cache/queue, services can't communicate

Interventions:

• Use Docker Compose integration

• Named volumes for persistence

• Health checks for service readiness

• Use assets/devcontainer-compose.md template

DV5: Dockerfile Issues

Symptoms: Build failures, huge images, no caching

Best Practices:

FROM mcr.microsoft.com/devcontainers/base:ubuntu

Dependencies first (cached)

RUN apt-get update && apt-get install -y
build-essential && rm -rf /var/lib/apt/lists/*

Copy deps then install (cached if deps unchanged)

COPY package*.json ./ RUN npm install

Code last (changes frequently)

COPY . .

DV6: Devcontainer Validated

Indicators:

• Startup under 2 minutes

• Works in VS Code and Codespaces

• New developers productive in 30 minutes

Available Scripts

Script Purpose Usage

analyze-devcontainer.ts

Find issues and optimizations deno run --allow-read scripts/analyze-devcontainer.ts

validate-dockerfile.ts

Check Dockerfile best practices deno run --allow-read scripts/validate-dockerfile.ts

scan-image.ts

Vulnerability scanning (wraps Trivy) deno run --allow-run scripts/scan-image.ts [image]

Anti-Patterns

The Kitchen Sink

Installing every tool "just in case" - 10+ minute startups. Fix: Start minimal. Add only when needed.

The postCreateCommand Overload

Everything in postCreateCommand - runs every time. Fix: Move stable operations to Dockerfile.

The Snowflake Container

Manual changes inside running containers. Fix: ALL changes go in config files.

Templates

• assets/devcontainer-simple.md

• Basic single-container setup

• assets/devcontainer-dockerfile.md

• Custom Dockerfile approach

• assets/devcontainer-compose.md

• Multi-service setup

Related Skills

• system-design - Multi-service architecture informs Compose config

• pwa-development - Consistent environment for PWA toolchain