Container runtime configuration

Containers & Runtime Configuration

Build containers that are small, deterministic, unprivileged, and responsive to operating-system lifecycle signals (SIGTERM), with explicit startup validation for all runtime configuration.

Production Multi-Stage Dockerfile Checklist

# Stage 1: Build with pinned base image and cached dependency layer
FROM node:22.14.0-bookworm-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src ./src
RUN npm run build && npm prune --omit=dev

# Stage 2: Minimal, non-root production runtime
FROM node:22.14.0-bookworm-slim AS runtime
ENV NODE_ENV=production
WORKDIR /app
COPY --from=build --chown=node:node /app/package.json ./
COPY --from=build --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/dist ./dist
USER node
EXPOSE 3000
# Exec form (JSON array) so the runtime process is PID 1 (or under tini/dumb-init) and receives SIGTERM!
CMD ["node", "dist/index.js"]

Five Non-Negotiable Container Rules

1. Exec form CMD / ENTRYPOINT & PID 1 Signal Handling:
   • Never use shell form CMD npm start or CMD node server.js. Shell form spawns /bin/sh -c as PID 1, which swallows SIGTERM on container stop, causing every deployment to hang until the 10–30 second SIGKILL timeout and dropping in-flight requests!
   • Invoke the binary directly in exec form (CMD ["node", "dist/index.js"]) or wrap with --init / tini so SIGTERM triggers your application's graceful shutdown handler (server.close(), DB pool drain).
2. Run as a non-root user:
   • Always switch to an unprivileged user (USER node, USER nonroot, or a dedicated UID/GID 10001) before CMD, and keep the root filesystem read-only where possible with explicit writable mounts (/tmp or volume paths).
3. Fail-fast runtime configuration validation:
   • Validate all required environment variables (PORT, DATABASE_URL, REDIS_URL, feature flags) at process startup using a strict schema before opening network listeners. Print every missing or invalid key name in one diagnostic error rather than crashing 20 minutes later on a code path.
4. Local parity with docker-compose:
   • Use healthcheck: + depends_on: { db: { condition: service_healthy } } in docker-compose.yml so application containers wait for Postgres/Redis/migrations to accept connections cleanly instead of crash-looping on cold start.
5. Log to stdout / stderr:
   • Never write application logs Exclusively to unrotated files inside an ephemeral container filesystem; emit structured logs to stdout/stderr and configure log rotation (max-size, max-file) on the container runtime.