devops-docker-patterns

Docker Patterns

Core Principles

1. Minimal images -- Use the smallest base image that satisfies your runtime requirements. Every unnecessary package increases attack surface and image size.
2. Immutable infrastructure -- Containers should be disposable and reproducible. Never patch a running container; rebuild and redeploy.
3. Layer caching -- Order Dockerfile instructions from least-frequently-changed to most-frequently-changed so Docker can reuse cached layers.
4. Security by default -- Run processes as non-root, scan images for vulnerabilities, and never bake secrets into images.
5. One process per container -- Each container should run a single concern. Use Compose or orchestrators to combine services.

---

Dockerfile Best Practices

Use multi-stage builds to separate build dependencies from the final runtime image. This keeps production images small and free of compilers, package managers, and source code.

# ---- Build stage ----
FROM python:3.12-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

# ---- Runtime stage ----
FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /install /usr/local
COPY . .
USER nobody
EXPOSE 8000
CMD ["gunicorn", "app:create_app()", "--bind", "0.0.0.0:8000"]

Order layers so that dependency installation comes before source code COPY. This way, code changes do not invalidate the expensive dependency-install layer.

See dockerfile-patterns for: multi-stage builds, ARG/ENV usage, COPY vs ADD, ENTRYPOINT vs CMD patterns, and .dockerignore configuration.

---

Docker Compose Patterns

Define services, networks, and volumes declaratively. Use depends_on with health checks to control startup order reliably.

services:
  api:
    build: .
    ports:
      - "8000:8000"
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/mydb
    networks:
      - backend

  db:
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks:
      - backend

volumes:
  pgdata:

networks:
  backend: