docker

Docker

Overview

Containerization, Dockerfile architecture, multi-stage compilation, security hardening, and container orchestration for production workloads.

When to Use

Activate when creating or optimizing Dockerfiles, docker-compose configurations, container security audits, CI/CD container build stages, or production container deployments.

Rules & Patterns

Negative Constraints (What NOT to Do)

1. NEVER run containers as root in production: Always create and switch to an unprivileged non-root user (e.g. USER node or USER nonroot).
2. NEVER use the latest tag: Always pin base images to specific immutable version digests or explicit minor tags (e.g. node:22-alpine3.20 or python:3.12-slim-bookworm).
3. NEVER copy source code before dependency manifests: Always copy package manifests (package.json, pnpm-lock.yaml, pyproject.toml) and install dependencies first to maximize Docker layer cache hits.
4. NEVER bake secrets, API keys, or .env files into image layers: Pass secrets via build-time secret mounts (--mount=type=secret) or runtime environment variables injected by the orchestrator.
5. NEVER include build tools or devDependencies in the final runner image: Always use multi-stage builds to discard compilers, package managers, and temporary build caches from production images.
6. NEVER run without a .dockerignore file: Always exclude .git, node_modules, .env*, and build outputs from the Docker build context.

---

Pattern 1: Node.js / Next.js Standalone Multi-Stage Dockerfile

Optimized multi-stage build producing minimal production images (<120MB) with non-root security:

# ── Stage 1: Dependencies ─────────────────────────────────────────────
FROM node:22-alpine3.20 AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

COPY package.json pnpm-lock.yaml* package-lock.json* yarn.lock* ./
RUN \
  if [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm i --frozen-lockfile; \
  elif [ -f package-lock.json ]; then npm ci; \
  else yarn --frozen-lockfile; \
  fi

# ── Stage 2: Builder ──────────────────────────────────────────────────
FROM node:22-alpine3.20 AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

ENV NEXT_TELEMETRY_DISABLED=1
ENV NODE_ENV=production
RUN npm run build

# ── Stage 3: Production Runner ────────────────────────────────────────
FROM node:22-alpine3.20 AS runner
WORKDIR /app

ENV NODE_ENV=production
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"

RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 nextjs

# Copy standalone output and static assets
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs
EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://127.0.0.1:3000/api/health || exit 1

CMD ["node", "server.js"]