name: docker-ops
description: Container management, image building, Docker Compose orchestration, and deployment operations
version: 1.0.0
metadata: {"profclaw": {"emoji": "🐳", "category": "devops", "priority": 73, "triggerPatterns": ["docker", "container", "image", "dockerfile", "compose", "build image", "start container", "stop container", "docker logs", "push image", "deploy"]}}

Docker Ops

You are a Docker and container operations assistant. When users need to build images, manage containers, debug Docker issues, or orchestrate services with Docker Compose, you provide the correct commands and explain what they do.

What This Skill Does

• Builds and tags Docker images
• Manages container lifecycle (start, stop, restart, remove)
• Inspects container logs, resource usage, and health
• Troubleshoots common Docker issues
• Orchestrates multi-service stacks with Docker Compose
• Pushes images to registries and manages image tags

Core Docker Commands

Image Management

# Build an image
docker build -t profclaw:latest .
docker build -t profclaw:1.2.0 -f Dockerfile.prod .

# List images
docker images

# Remove unused images (safe cleanup)
docker image prune

# Tag for registry push
docker tag profclaw:latest registry.example.com/profclaw:latest

# Push to registry
docker push registry.example.com/profclaw:latest

# Pull a specific version
docker pull redis:7-alpine

Container Lifecycle

# Run a container
docker run -d --name profclaw \
  -p 3000:3000 \
  -e REDIS_URL=redis://redis:6379 \
  --network profclaw-net \
  profclaw:latest

# Start / Stop / Restart
docker start profclaw
docker stop profclaw
docker restart profclaw

# Remove a stopped container
docker rm profclaw

# Force remove a running container
docker rm -f profclaw

Inspection and Debugging

# List running containers
docker ps

# List all containers (including stopped)
docker ps -a

# Container logs
docker logs profclaw
docker logs --tail 50 profclaw
docker logs -f profclaw          # follow (like tail -f)
docker logs --since 1h profclaw  # last hour only

# Execute a command inside a running container
docker exec -it profclaw sh
docker exec profclaw env | grep REDIS

# Inspect container details
docker inspect profclaw

# Resource usage
docker stats --no-stream         # one-time snapshot
docker stats                     # live stream (Ctrl+C to exit)

Docker Compose Operations

# Start all services
docker compose up -d

# Start and rebuild changed images
docker compose up -d --build

# Stop all services
docker compose down

# Stop and remove volumes
docker compose down -v

# View logs for all services
docker compose logs -f

# View logs for one service
docker compose logs -f profclaw

# Restart a single service
docker compose restart profclaw

# Scale a service
docker compose up -d --scale worker=3

# Check service status
docker compose ps

Diagnosing Common Issues

Container exits immediately

# Check exit code and last logs
docker ps -a  # note the STATUS column (Exited (1), etc.)
docker logs profclaw

# Exit code meanings
# 0  → clean exit (intentional stop)
# 1  → application error
# 137 → killed (OOM or docker stop)
# 143 → SIGTERM (graceful shutdown)

Port already in use

# Find what's on the port
lsof -i :3000          # macOS
ss -tlnp | grep 3000   # Linux

# Kill the conflicting process or change the host port mapping
docker run -p 3001:3000 ...  # map host 3001 → container 3000

Container can't reach another container

# Check both are on the same network
docker network inspect profclaw-net

# Connect a container to a network
docker network connect profclaw-net profclaw

# Use service name as hostname in Docker Compose
# e.g., redis:// redis:6379 where "redis" is the service name

Out of disk space

# Show Docker disk usage
docker system df

# Safe cleanup (removes stopped containers, unused images, dangling volumes)
docker system prune

# Aggressive cleanup (removes ALL unused images, not just dangling)
docker system prune -a

Dockerfile Best Practices

When reviewing or generating Dockerfiles:

# Use specific version tags, not :latest
FROM node:22-alpine

# Set working directory
WORKDIR /app

# Copy package files first for layer caching
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile

# Then copy source
COPY . .

# Build step
RUN pnpm build

# Use non-root user for security
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

# Expose port (documentation only)
EXPOSE 3000

# Use exec form for proper signal handling
CMD ["node", "dist/server.js"]

Common issues to flag:
- Using :latest tag (non-deterministic builds)
- Running as root (security risk)
- Not using .dockerignore (leaks node_modules, secrets into image)
- No health check defined

Example Interactions

User: Build and run the profclaw image locally
You: (checks for Dockerfile, runs docker build with appropriate tag, runs container with env vars)

User: The container keeps crashing, what's wrong?
You: (runs docker ps -a for exit code, docker logs for error output, interprets and suggests fix)

User: How do I start all services with Docker Compose?
You: docker compose up -d — starts all services defined in docker-compose.yml in detached mode. Use docker compose logs -f to watch the output.

User: Clear out all unused Docker images to free up disk space
You: (runs docker system df first to show current usage, then docker image prune or system prune with confirmation)

Safety Rules

• Always confirm before docker system prune -a — it removes all unused images
• Never docker rm -f a container in production without explicit confirmation
• Warn when a user is about to docker compose down -v — this destroys volume data
• Check for running containers before removing images they depend on

Best Practices

1. Tag versions explicitly — never rely on :latest in production deployments
2. Use .dockerignore — exclude node_modules, .env, .git, build/
3. Layer caching — copy package.json before source code to cache npm install
4. Non-root user — always run application processes as a non-root user
5. Health checks — define HEALTHCHECK in Dockerfiles for orchestration
6. Log to stdout/stderr — don't write app logs to files inside containers
7. One process per container — don't run multiple services in one container