Docker Image building best practices

Start with the Right Base Image

• Minimal images: Use distroless, alpine, or scratch where possible to reduce attack surface and image size.
• OS vs language runtime: Choose between OS images (ubuntu, debian) and language-specific images (python, node) carefully.
• Security updates: Always pick images that are actively maintained to avoid vulnerabilities.
• Pin versions: Avoid latest tags; use specific tags to ensure reproducibility.

Multi-Stage Builds

• Why: Reduces final image size, keeps build tools separate from runtime.
• Example pattern: FROM golang:1.21 AS builder WORKDIR /app COPY . . RUN go build -o myapp FROM gcr.io/distroless/base COPY --from=builder /app/myapp /myapp CMD ["/myapp"]

Layer Optimization

• Minimize layers: Each RUN, COPY, ADD creates a new layer. Combine commands when possible.
• Order matters: Cache-friendly layering can drastically reduce build time. # Install dependencies first (less likely to change) COPY go.mod go.sum ./ RUN go mod download # Then copy source code (more likely to change) COPY . .
• Clean after installing: Remove package manager caches, temp files to reduce image size. RUN apt-get update && apt-get install -y

Security Hardened Images

• Drop root user: RUN useradd -m appuser USER appuser
• Read-only filesystem: Use --read-only when running containers.
• Minimize attack surface: Only include necessary binaries and libraries.
• Scan images: Use tools like Trivy, Clair, Anchore to detect vulnerabilities before pushing to registry.

Efficient Caching and Build Performance

• Leverage Docker BuildKit: DOCKER_BUILDKIT=1 docker build .
• Cache dependencies separately: Dependencies change less often than code.
• Avoid cache-busting unnecessarily: Be strategic with ADD and COPY.

Environment and Config Management

• Avoid hardcoding secrets: Use Docker secrets or environment variables.
• Config files: Mount configs at runtime instead of baking them into the image.
• Immutable images: Treat images as stateless; runtime state should live outside the container.

Image Size Reduction Strategies

• Remove unnecessary files (docs, tests)
• Use distroless images where possible
• Strip binaries and compress layers
• Analyze images using dive or docker image inspect to see layer sizes