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