---
name: containerizing-services
description: Containerizes backend services with production-grade Dockerfiles — multi-stage builds, pinned base images, non-root users, healthchecks, and small images. Use when the user asks to write or review a Dockerfile, dockerize or containerize a service or app, shrink a Docker image, or fix container build or security issues. Do not use for Kubernetes manifests or orchestration, docker-compose service topology, or CI pipeline design (shipping-with-ci-cd).
---

<!--
Author: Simon-Pierre Boucher
Contact: contact@spboucher.ai
-->

# Containerizing Services

## When to use / when NOT to use
- **Use for:** writing or reviewing Dockerfiles, image size/security hardening, build-cache problems.
- **Do NOT use for:** Kubernetes/orchestration, compose topology, CI pipelines (shipping-with-ci-cd), or app code changes.

## Core rules

1. **Multi-stage: build heavy, run slim.** Compile/install in a build stage; copy only artifacts into the runtime stage.
   - ✅ `FROM node:22.4-slim AS build` … `FROM node:22.4-slim` + `COPY --from=build /app/dist ./dist`
   - ❌ One stage that ships compilers, dev deps, and source history.
2. **Pin base images.** Exact tag minimum; digest for production.
   - ✅ `FROM python:3.12.4-slim@sha256:…`
   - ❌ `FROM python:latest`
3. **Run as non-root.** Create a user and switch: `USER app`. Root-only containers fail most cluster policies and widen every exploit.
4. **Order layers for cache.** Copy dependency manifests and install BEFORE copying source, so code edits don't bust the dependency layer.
   - ✅ `COPY package*.json ./` → `RUN npm ci` → `COPY . .`
   - ❌ `COPY . .` first (every commit reinstalls everything).
5. **One process per container.** No supervisord bundles; sidecars belong to the orchestrator. Logs go to stdout/stderr only — never files inside the container.
6. **Ship a `.dockerignore`.** At minimum: `.git`, `node_modules`/venvs, `.env*`, secrets, test fixtures. Never `COPY` a secret; pass at runtime.
7. **Define `HEALTHCHECK`** (or document the orchestrator probe) hitting a real readiness endpoint, not `/`.
8. **Default slim/distroless; alpine only knowingly.** musl breaks some native wheels/binaries — use alpine only after the app is verified on it.

## Workflow

1. Pick runtime base (`<lang>:<exact-version>-slim` default; distroless escape hatch for static binaries).
2. Write `.dockerignore` before the Dockerfile.
3. Write multi-stage Dockerfile per rules 1–8.
4. Build: `docker build -t svc:dev .` — rebuild after touching one source file and confirm the dependency layer is cached (`CACHED` in output).
5. Validate: `docker run --rm svc:dev id -u` returns non-zero UID; `docker inspect --format='{{.Config.Healthcheck}}' svc:dev` is set; `docker run --rm --read-only svc:dev` starts (add tmpfs mounts if the app needs scratch dirs).
6. Check size: `docker images svc:dev` — if the runtime image exceeds ~2× the artifact size, find what leaked in (`docker history svc:dev`).

## Edge cases & failure modes
- **Native deps fail on slim** → install build tools in the build stage only (`apt-get install -y --no-install-recommends build-essential`), never in runtime.
- **Secrets needed at build time** → `RUN --mount=type=secret,id=npm_token …` (BuildKit); never `ARG` a secret (it persists in history).
- **Image works locally, fails in cluster as non-root** → files owned by root; `COPY --chown=app:app`.
- **Timezone/CA errors in distroless** → use the `:debug` or cc variant, or copy `ca-certificates` from the build stage.

## References
Deeper recipes and gotchas: see [references/patterns.md](references/patterns.md).