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