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 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](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](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