Docker Development Skill
Execute all package installations and code execution inside Docker containers. This keeps the host machine clean and ensures consistent environments across projects.
Behavioral Classification
Type: Autonomous Execution
Directive: EXECUTE, DON'T ASK
This skill enforces Docker-first development automatically. When you request npm/node operations, commands are executed inside Docker without asking for permission.
Enforcement Behavior:
- Blocks host-machine npm/node commands
- Suggests or transforms commands to use
docker exec - Automatically checks container status before operations
Quick Start
For new projects, see [setup.md](setup.md) for the complete first-time setup guide.
Minimal setup:
# 1. Start container
docker compose --profile dev up -d
# 2. Verify running
docker ps --filter "name=my-project"
# 3. Run commands in container
docker exec my-project-dev-1 npm install
docker exec my-project-dev-1 npm test
docker exec my-project-dev-1 npm run buildENFORCEMENT RULES
BLOCKED: Never Run on Host
These commands are BLOCKED on the host machine:
npm install, npm ci, npm run, npm test, npm exec
npx <anything>
yarn add, yarn install, yarn run
pnpm add, pnpm install, pnpm run
node <script>
tsx <script>
bun <script>Why? Installing packages on the host:
- Pollutes the host machine with project-specific dependencies
- Creates version conflicts between projects
- Makes environments non-reproducible
- Can cause security issues with global packages
REQUIRED: Use docker exec
All Node.js commands MUST use this prefix:
docker exec <container-name> <command>Note: Use docker exec WITHOUT the -it flag in Claude Code:
# Correct (works in Claude Code)
docker exec my-project-dev-1 npm run build
# Wrong (fails with "not a TTY")
docker exec -it my-project-dev-1 npm run buildPre-Flight Check (MANDATORY)
Before running ANY npm/node command, verify the container is running.
docker ps --filter "name=<container-name>" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"Expected output:
NAMES STATUS PORTS
my-project-dev-1 Up X minutes 0.0.0.0:3000->3000/tcpIf container is NOT running:
cd /path/to/project
docker compose --profile dev up -d
docker ps --filter "name=<container-name>"If container shows "Exited":
docker logs <container-name> --tail 20
docker compose --profile dev down
docker compose --profile dev up -dQuick Reference
Check Container Status
docker ps --filter "name=<container-name>"
docker logs <container-name> --tail 50
curl -s http://localhost:<port> > /dev/null && echo "Running" || echo "Not running"Start/Stop Containers
docker compose --profile dev up -d # Start
docker compose --profile dev down # Stop
docker compose --profile dev restart dev # Restart
docker compose --profile dev up -d --build # RebuildExecute Commands Inside Container
docker exec <container> npm install <package> # Install package
docker exec <container> npm install -D <package> # Install dev dependency
docker exec <container> npm test # Run tests
docker exec <container> npm run typecheck # Type checking
docker exec <container> npm run lint # Linting
docker exec <container> npm run build # Build
docker exec <container> /bin/sh # Shell (use -it for interactive)When to Use docker exec
| Operation | Use docker exec? | Reason | |-----------|------------------|--------| | npm install | Always | Packages install in container only | | npm run dev | No | Already running via docker-compose | | npm test | Yes | Tests run in container environment | | npm run build | Yes | Build happens in container | | git commands | No | Git runs on host (manages files) | | File editing | No | Volume mount syncs automatically | | Database migrations | Yes | Uses container's Node environment |
Container Architecture
┌─────────────────────────────────────────────────────────────┐
│ HOST (macOS/Linux/Windows) │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Docker Container (my-project-dev-1) │ │
│ │ │ │
│ │ Node 20 (Slim or Alpine) │ │
│ │ └── node_modules/ (container-only, NOT on host) │ │
│ │ └── Dev server (port 3000) │ │
│ │ │ │
│ │ Volume Mounts: │ │
│ │ └── .:/app (source code sync) │ │
│ │ └── node_modules:/app/node_modules (persist deps) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Port mapped │
│ │ │
│ ▼ │
│ http://localhost:<port> │
└─────────────────────────────────────────────────────────────┘Key Point: node_modules exists ONLY in the container. The host machine stays clean.
Volume Mount Behavior
volumes:
- .:/app # Source code (synced)
- node_modules:/app/node_modules # Dependencies (container-only)What this means:
- Source code changes on host are immediately visible in container
node_modules/lives in a named Docker volume, NOT on host filesystem- Hot reload works automatically
- Host machine never has project dependencies installed
Troubleshooting
Container Not Running
docker ps -a --filter "name=<container-name>"
docker logs <container-name>
docker compose --profile dev up -dPort Already in Use
lsof -i :<port>
# Kill the process or change port in docker-compose.ymlModule Not Found Errors
docker compose --profile dev down
docker compose --profile dev build --no-cache
docker compose --profile dev up -d
docker exec <container> npm installFile Changes Not Reflecting
docker inspect <container-name> | grep -A 10 "Mounts"
docker compose --profile dev restart devWrong Architecture (M1/M2 Mac)
If you see platform warnings:
# Add to docker-compose.yml service
platform: linux/amd64 # or linux/arm64Native Module Errors
See [setup.md](setup.md) for the complete native module troubleshooting guide including:
ERR_DLOPEN_FAILEDresolution- Alpine vs Slim decision tree
- Rebuild instructions
Best Practices
- Always check container status before running commands
- Use docker exec for ALL npm/node operations
- Never install packages on host - always in container
- Use node:20-slim by default - switch to alpine only if no native modules
- Rebuild image after changing
package.jsonorDockerfile - Check logs when something isn't working
- Use named volumes for node_modules to persist between container restarts
Health Checks
For automated health monitoring and CI integration, see [health-checks.md](health-checks.md):
- Container healthcheck configuration
- Health check shell script
- NPM scripts integration
- Troubleshooting health failures
Integration with Claude Code
| Task | Action | |------|--------| | Install dependency | docker exec <container> npm install <pkg> | | Run tests | docker exec <container> npm test | | Check types | `docker exec <container> npm run type