bouclem 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.mdtemplate
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.mdtemplate
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 setupassets/devcontainer-dockerfile.md- Custom Dockerfile approachassets/devcontainer-compose.md- Multi-service setup
Related Skills
- system-design - Multi-service architecture informs Compose config
- pwa-development - Consistent environment for PWA toolchain