docker

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_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

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, 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

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