Docker Containerization

Never use latest tag in production. Always pin to specific version + digest for reproducibility.

</essential_principles>

<multi_stage_builds>

Every production Dockerfile should use multi-stage builds. Separate build dependencies from runtime.

Go Application

# syntax=docker/dockerfile:1

# ── Build stage ──────────────────────────────────────────
FROM golang:1.24-bookworm AS builder

WORKDIR /src

# Cache dependencies separately from source code
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod \
    go mod download

# Copy source and build
COPY . .
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
    go build -ldflags="-s -w -X main.version=${VERSION}" \
    -o /bin/app ./cmd/app/

# ── Runtime stage ────────────────────────────────────────
FROM gcr.io/distroless/static-debian12:nonroot

COPY --from=builder /bin/app /app

EXPOSE 8080
ENTRYPOINT ["/app"]

Node.js Application

# syntax=docker/dockerfile:1

# ── Dependencies stage ───────────────────────────────────
FROM node:22-slim AS deps

WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci --production=false

# ── Build stage ──────────────────────────────────────────
FROM deps AS builder

COPY . .
RUN npm run build

# ── Production dependencies ──────────────────────────────
FROM node:22-slim AS prod-deps

WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci --omit=dev

# ── Runtime stage ────────────────────────────────────────
FROM node:22-slim

RUN groupadd -r appuser && useradd -r -g appuser -d /app appuser
WORKDIR /app

COPY --from=prod-deps /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
COPY package.json ./

USER appuser
EXPOSE 3000
CMD ["node", "dist/index.js"]

React SPA (Vite)

# syntax=docker/dockerfile:1

# ── Build stage ──────────────────────────────────────────
FROM node:22-slim AS builder

WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci

COPY . .
RUN npm run build

# ── Runtime stage (static files served by nginx) ────────
FROM nginx:1.27-alpine

COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

Key Principles:

• Always start with # syntax=docker/dockerfile:1 to enable BuildKit features
• Copy dependency manifests first, then source (maximizes cache hits)
• Use --mount=type=cache for package manager caches
• Strip debug symbols in Go builds: -ldflags="-s -w"
• Set CGO_ENABLED=0 for Go when targeting scratch/distroless

</multi_stage_builds>

Non-Negotiable Security Practices:

1. Run as non-root:

# For distroless: use the nonroot tag
FROM gcr.io/distroless/static-debian12:nonroot

# For other images: create a dedicated user
RUN groupadd -r appuser && useradd -r -g appuser -s /usr/sbin/nologin appuser
USER appuser

1. Never embed secrets in images:

# WRONG -- secret baked into layer history
COPY .env /app/.env
ENV DATABASE_PASSWORD=hunter2

# RIGHT -- use build secrets (never persisted in image)
RUN --mount=type=secret,id=db_password \
    cat /run/secrets/db_password > /dev/null

# RIGHT -- pass at runtime via environment or mounted secrets
# docker run -e DATABASE_PASSWORD=... app
# docker run -v /secrets/db_password:/run/secrets/db_password:ro app

1. Read-only root filesystem:

# docker-compose.yml