majiayu000 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 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 build
ENFORCEMENT 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 build
Pre-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/tcp
If 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 -d
Quick 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 # Rebuild
Execute 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 -d
Port Already in Use
lsof -i :<port>
# Kill the process or change port in docker-compose.yml
Module 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 install
File Changes Not Reflecting
docker inspect <container-name> | grep -A 10 "Mounts"
docker compose --profile dev restart dev
Wrong Architecture (M1/M2 Mac)
If you see platform warnings:
# Add to docker-compose.yml service
platform: linux/amd64 # or linux/arm64
Native Module Errors
See 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:
- 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 typecheck |
| Build project | docker exec <container> npm run build |
| Start dev server | Container already runs it via docker-compose |
| Edit files | Edit directly (volume mount syncs) |
| Git operations | Run on host (not in container) |
Related Skills
For complete Docker development support, use with these complementary skills:
| Skill | Purpose |
|---|---|
| docker-enforce | Automatically blocks/transforms host commands to run inside Docker |
| docker-optimizer | Analyzes Dockerfiles for optimization opportunities |
| docker-guard | Prevents hangs when Docker daemon is unresponsive |
docker-enforce
Provides automated enforcement of Docker-first policy:
- Intercepts
npm,npx,yarn,pnpm,node,tsx,buncommands - Blocks commands on host with suggestion to use
docker exec - Can auto-transform commands to run inside container
- Configurable allowlist for safe host commands
Install: git clone https://github.com/wrsmith108/docker-enforce.git ~/.claude/skills/docker-enforce
Reference Documentation
| Document | Contents |
|---|---|
| setup.md | First-time setup, native module troubleshooting, project configuration |
| health-checks.md | Container healthchecks, monitoring scripts, NPM integration |
Changelog
v1.1.0 (2026-01-23)
- Refactor: Decompose into sub-files for progressive disclosure
- Extract first-time setup to setup.md
- Extract health checks to health-checks.md
- Add Behavioral Classification section (ADR-025)
- Main SKILL.md reduced from 718 to ~320 lines
v1.0.0 (2025-01)
- Initial release
- Docker-first enforcement rules
- Container architecture documentation
- Troubleshooting guide
Last updated: January 2026