docker-ops

name	docker-ops
description	Docker containerization patterns, Dockerfile best practices, multi-stage builds, and Docker Compose. Use for: docker, Dockerfile, docker-compose, container, image, multi-stage build, docker build, docker run, .dockerignore, health check, distroless, scratch image, BuildKit, layer caching, container security.
license	MIT
allowed-tools	Read Write Bash
metadata	{"author":"claude-mods","related-skills":"container-orchestration, go-ops, rust-ops, ci-cd-ops"}

Docker Operations

Comprehensive Docker patterns for building, running, and composing containerized applications.

Dockerfile Best Practices

Practice	Do	Don't
Base image	FROM node:20-slim	FROM node:latest
Layer caching	Copy dependency files first, then source	COPY . . before RUN install
Package install	apt-get update && apt-get install -y ... && rm -rf /var/lib/apt/lists/*	Separate RUN for update and install
User	USER nonroot (create if needed)	Run as root in production
Multi-stage	Separate build and runtime stages	Ship compiler toolchains
Secrets	--mount=type=secret (BuildKit)	COPY .env . or ARG PASSWORD
ENTRYPOINT vs CMD	ENTRYPOINT for fixed binary, CMD for defaults	Relying on shell form for signal handling
WORKDIR	WORKDIR /app	RUN cd /app && ...
.dockerignore	Include .git, node_modules, __pycache__	No .dockerignore at all
Labels	LABEL org.opencontainers.image.*	No metadata

Multi-Stage Build Decision Tree

Choose your runtime base image by language:

Go ──────────── CGO disabled? ──── Yes ──► scratch or distroless/static
                                   No ───► distroless/base or alpine

Rust ─────────── Static musl? ──── Yes ──► scratch or distroless/static
                                   No ───► distroless/cc or debian-slim

Node.js ──────── Need native? ──── Yes ──► node:20-slim
                                   No ───► node:20-alpine (smaller)

Python ────────── Need C libs? ─── Yes ──► python:3.12-slim
                                   No ───► python:3.12-slim (still slim)

Java ──────────── JRE only ──────────────► eclipse-temurin:21-jre-alpine

See: references/multi-stage-builds.md for complete annotated examples per language.

Layer Caching Rules

Docker caches each layer. A cache miss at layer N invalidates all subsequent layers.

What Invalidates Cache

Trigger	Effect
Changed file in COPY/ADD	Invalidates this layer + all below
Changed RUN command text	Invalidates this layer + all below
Changed ARG value	Invalidates from the ARG declaration down
--no-cache flag	Invalidates everything
Base image update	Invalidates everything

Optimal Layer Order

# 1. Base image (changes rarely)
FROM python:3.12-slim

# 2. System dependencies (changes rarely)
RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# 3. Dependency files (changes occasionally)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 4. Application code (changes frequently)
COPY src/ ./src/

# 5. Runtime config (changes frequently)
CMD ["python", "-m", "app"]

Rule of thumb: Order layers from least-frequently-changed to most-frequently-changed.

.dockerignore Essentials

# Version control
.git
.gitignore

# Dependencies (rebuilt in container)
node_modules
__pycache__
*.pyc
.venv
vendor/

# Build artifacts
dist/
build/
target/
*.egg-info

# IDE and editor
.vscode
.idea
*.swp
*.swo

# Docker files (prevent recursive context)
Dockerfile*
docker-compose*
.dockerignore

# Environment and secrets
.env
.env.*
*.pem
*.key

# Documentation and tests (unless needed)
docs/
tests/
*.md
LICENSE

Why it matters: Without .dockerignore, docker build sends the entire context directory to the daemon. A .git folder alone can add hundreds of megabytes.

Docker Compose Quick Reference

Service Definition

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
      target: production        # Multi-stage target
    image: myapp:latest
    ports:
      - "8080:8000"
    environment:
      DATABASE_URL: postgres://db:5432/app
    env_file:
      - .env
    volumes:
      - ./src:/app/src          # Bind mount (dev)
      - app-data:/app/data      # Named volume (persistent)
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    restart: unless-stopped
    networks:
      - backend

Volumes and Networks

volumes:
  app-data:           # Named volume (Docker-managed)
  db-data:
    driver: local

networks:
  backend:
    driver: bridge
  frontend:
    driver: bridge

See: references/compose-patterns.md for full patterns including profiles, watch mode, and override files.

Security Quick Reference

Area	Recommendation
User	Run as non-root: RUN adduser -D appuser && USER appuser
Base image	Pin digest: FROM python:3.12-slim@sha256:abc123...
Filesystem	Read-only root: docker run --read-only --tmpfs /tmp
Capabilities	Drop all, add needed: --cap-drop=ALL --cap-add=NET_BIND_SERVICE
Secrets	BuildKit secrets: RUN --mount=type=secret,id=key cat /run/secrets/key
Scanning	Scan images: trivy image myapp:latest or grype myapp:latest
No latest	Always use specific tags and pin versions
Minimal image	Use distroless or scratch when possible
No SUID	RUN find / -perm /6000 -type f -exec chmod a-s {} +
Network	Use internal networks for backend services

Non-Root User Pattern

# Debian/Ubuntu-based
RUN groupadd -r appuser && useradd -r -g appuser -d /app -s /sbin/nologin appuser
COPY --chown=appuser:appuser . /app
USER appuser

# Alpine-based
RUN addgroup -S appuser && adduser -S -G appuser appuser
COPY --chown=appuser:appuser . /app
USER appuser

# Distroless (built-in nonroot user)
FROM gcr.io/distroless/static:nonroot
USER nonroot:nonroot

Common Gotchas

Gotcha	Problem	Fix
Large images	Shipping build tools, node_modules in final image	Multi-stage builds
Cache busting	COPY . . before RUN npm install	Copy lockfile first, install, then copy source
Secrets in layers	COPY .env . or ARG SECRET=... bakes secrets into image history	Use --mount=type=secret or runtime env vars
PID 1 problem	App doesn't receive SIGTERM, zombie processes	Use tini as init or exec form for CMD
Timezone	Container uses UTC	Set TZ env var or install tzdata
DNS caching	Alpine musl DNS issues	Use RUN apk add --no-cache libc6-compat or switch to slim
apt cache	apt-get update cached from old layer	Always combine update && install in one RUN
Missing signals	Shell form (CMD npm start) wraps in /bin/sh	Exec form: CMD ["node", "server.js"]
Build context size	Sending GB of data to daemon	Add .dockerignore, check with docker build --progress=plain
Layer explosion	Each RUN creates a layer	Chain related commands with &&

PID 1 / Signal Handling Fix

# Option 1: Use tini as init process
RUN apt-get update && apt-get install -y --no-install-recommends tini \
    && rm -rf /var/lib/apt/lists/*
ENTRYPOINT ["tini", "--"]
CMD ["node", "server.js"]

# Option 2: Docker init flag (Docker 23.0+)
# docker run --init myapp

# Option 3: Node.js - handle signals in code
# process.on('SIGTERM', () => { server.close(); process.exit(0); });

Essential Docker Commands

# Build
docker build -t myapp:1.0 .
docker build -t myapp:1.0 --target production .    # Multi-stage target
docker build --no-cache -t myapp:1.0 .              # Force rebuild

# Run
docker run -d --name myapp -p 8080:8000 myapp:1.0
docker run --rm -it myapp:1.0 /bin/sh               # Interactive debug
docker run --read-only --tmpfs /tmp myapp:1.0        # Read-only root

# Inspect
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"
docker history myapp:1.0                             # Layer breakdown
docker inspect myapp:1.0 | jq '.[0].Config'         # Image config

# Debug running container
docker exec -it myapp /bin/sh
docker logs -f myapp
docker stats myapp

# Cleanup
docker system prune -a --volumes                     # Remove everything unused
docker image prune -a                                # Remove unused images

Reference Files

File	Contents
references/multi-stage-builds.md	Per-language multi-stage patterns (Go, Rust, Node, Python)
references/compose-patterns.md	Compose services, networking, profiles, watch, overrides
references/optimization.md	Image size, BuildKit, security scanning, debugging