Docker Development Skill

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

---

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_FAILED resolution
• Alpine vs Slim decision tree
• Rebuild instructions

---

Best Practices

1. Always check container status before running commands
2. Use docker exec for ALL npm/​node operations
3. Never install packages on host - always in container
4. Use node:20-slim by default - switch to alpine only if no native modules
5. Rebuild image after changing package.json or Dockerfile
6. Check logs when something isn't working
7. 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

---

Related Skills

For complete Docker development support, use with these complementary skills:

docker-enforce

Provides automated enforcement of Docker-first policy:

• Intercepts npm, npx, yarn, pnpm, node, tsx, bun commands
• 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

---

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