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.

Configuration

Before using this skill, identify your project's container name:

# Find your container name
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Common naming patterns:

• {project-name}-dev-1 (docker-compose)
• {project-name}_dev_1 (older docker-compose)
• Custom names from container_name: in docker-compose.yml

Core Principle

NEVER run npm, node, npx, or project scripts directly on the host machine.

Instead, use docker exec or ensure the container is running the dev server.

Pre-Flight Check (MANDATORY)

Before running ANY npm/node command, verify the container is running:

# Check if container is running (replace with your container name)
docker ps --filter "name=YOUR_CONTAINER" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

If container is NOT running:

# Navigate to project root
cd /path/to/your/project

# Start container (common patterns)
docker-compose up -d                    # Simple setup
docker-compose --profile dev up dev -d  # Profile-based setup
docker compose up -d                    # Docker Compose V2

# Verify it started
docker ps --filter "name=YOUR_CONTAINER"

If container shows "Exited":

# Check why it exited
docker logs YOUR_CONTAINER --tail 20

# Remove and restart
docker-compose down
docker-compose up -d

Quick Reference

Check Container Status

# List all running containers
docker ps

# Filter by project name
docker ps --filter "name=PROJECT_NAME"

# Check container logs
docker logs CONTAINER_NAME --tail 50

# Follow logs in real-time
docker logs CONTAINER_NAME -f

Start/Stop Containers

# Start containers (from project root)
docker-compose up -d

# Start with specific profile
docker-compose --profile dev up -d

# Stop containers
docker-compose down

# Restart
docker-compose restart

# Rebuild after Dockerfile changes
docker-compose up -d --build

Execute Commands Inside Container

# Install a package
docker exec -it CONTAINER_NAME npm install PACKAGE_NAME

# Install dev dependency
docker exec -it CONTAINER_NAME npm install -D PACKAGE_NAME

# Run tests
docker exec -it CONTAINER_NAME npm test

# Run type checking
docker exec -it CONTAINER_NAME npm run typecheck

# Run linting
docker exec -it CONTAINER_NAME npm run lint

# Run build
docker exec -it CONTAINER_NAME npm run build

# Open shell inside container
docker exec -it CONTAINER_NAME /bin/sh

# Run with environment variable
docker exec -it -e MY_VAR=value CONTAINER_NAME command

When to Use docker exec

Operation	Use docker exec?	Reason
npm install	✅ Yes	Packages install in container
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                                   │   │
│  │                                                     │   │
│  │  Node/Python/Go/etc.                               │   │
│  │  └── dependencies (container-only)                 │   │
│  │  └── Dev server (exposed port)                     │   │
│  │                                                     │   │
│  │  Volume Mounts:                                     │   │
│  │  └── .:/app (source code sync)                      │   │
│  │  └── node_modules:/app/node_modules (persist deps)  │   │
│  └─────────────────────────────────────────────────────┘   │
│                         │                                   │
│                         ▼                                   │
│                   Port X mapped                             │
│                         │                                   │
│                         ▼                                   │
│              http://localhost:PORT                          │
└─────────────────────────────────────────────────────────────┘

Volume Mount Behavior

Typical docker-compose.yml volume configuration:

volumes:
  - .:/app                           # Source code (synced)
  - /app/node_modules                # Dependencies (container-only)

What this means:

• Source code changes on host are immediately visible in container
• node_modules/ in container is separate from any on host
• Hot reload works automatically with most frameworks

Troubleshooting

Container Not Running

# Check if container exists (including stopped)
docker ps -a --filter "name=PROJECT_NAME"

# If exited, check why
docker logs CONTAINER_NAME

# Remove stopped containers and restart
docker-compose down
docker-compose up -d

Port Already in Use

# Find what's using the port
lsof -i :PORT
# or
netstat -tulpn | grep PORT

# Kill the process or change port in docker-compose.yml

Module Not Found Errors

# Rebuild container with fresh dependencies
docker-compose down
docker-compose build --no-cache
docker-compose up -d

File Changes Not Reflecting

# Check volume mounts
docker inspect CONTAINER_NAME | grep -A 10 "Mounts"

# Restart container
docker-compose restart

Permission Errors

# Fix ownership issues (Linux)
docker exec -it CONTAINER_NAME chown -R node:node /app

# Or run as root temporarily
docker exec -u root -it CONTAINER_NAME command

docker-compose.yml Template

version: '3.8'

services:
  dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    container_name: myproject-dev
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      - NODE_ENV=development
    command: npm run dev -- --host 0.0.0.0

volumes:
  node_modules:

Dockerfile.dev Template

FROM node:20-alpine

WORKDIR /app

# Install dependencies first (better caching)
COPY package*.json ./
RUN npm ci

# Copy source code
COPY . .

# Expose port
EXPOSE 3000

# Start dev server
CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0"]

Best Practices

1. Always check container status before running commands
2. Use docker exec for all npm/node operations
3. Let volume mounts handle file syncing (no manual copying)
4. Rebuild image after changing package.json or Dockerfile
5. Check logs if something isn't working
6. Use named volumes for node_modules to persist dependencies
7. Expose ports with --host 0.0.0.0 so host can access the server

Integration with Claude Code

When Claude Code needs to:

Task	Action
Install dependency	docker exec -it CONTAINER npm install PKG
Run tests	docker exec -it CONTAINER npm test
Check types	docker exec -it CONTAINER npm run typecheck
Build project	docker exec -it 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)

Project Discovery

To auto-detect container name, check these sources:

1. docker-compose.yml → container_name: field
2. docker ps → running containers
3. .claude/settings.local.json → project-specific config
4. Pattern: {directory-name}-dev-1

---

For project-specific Docker configuration, create .claude/settings.local.json with your container name.