Container runtime configuration

Makes container startup and shutdown predictable through explicit configuration validation, process signals and production runtime boundaries.

containers-runtime-config

Team members using this skill

AgentOtto

See how it helps

When is it useful?

Use when containers fail at startup, ignore shutdown signals or behave differently between environments.

What does it help you do?

Builds a minimal runtime with an unprivileged user and pinned inputs.
Validates required configuration before opening listeners without printing secrets.
Connects signal handling, readiness and structured logs to operational recovery.

Try asking this

Review a container that hangs on shutdown and starts before its database becomes ready. Delay database startup and send a termination signal during a request. Readiness must stay false until usable, and shutdown must finish within its deadline.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

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

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).
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).
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.
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.
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.

Included files 1

SKILL.md