0xDarkMatter/docker-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 |