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 ```dockerfile # 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 ```dockerignore # 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 ```yaml 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 ```yaml 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 ```dockerfile # 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 ```dockerfile # 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 ```bash # 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 |