Stage 4 · Production · Chapter 18 of 20 · 7 min read

Production-ready images: users, healthchecks and limits

The same container that works on your laptop can still be too big, too privileged and too trusting for a server. Five habits fix most of it.

The checklist

An image that runs on your laptop is not yet an image you want on a server. Four habits close most of the gap.

Small base images

Every package in the base is something to download, store and patch. Start from the smallest base your app runs on, and use a multi-stage build (chapter 4) so compilers never reach it.

Pin the tag (chapter 2). For fully repeatable builds, pin the digest too: FROM node:22-slim@sha256:….

Run as a non-root user

Add a user in the Dockerfile and switch to it with USER. Everything after that line, and the running container, uses it. Files you COPY are owned by root unless you add --chown.

# Alpine
RUN addgroup -S app && adduser -S app -G app
USER app

# Debian / Ubuntu
RUN groupadd -r app && useradd -r -g app app
USER app

A non-root process cannot bind ports below 1024, so listen on 3000 or 8080 inside and publish whatever you like outside.

Healthchecks

“Running” only means the process exists. A HEALTHCHECK asks the app itself whether it is working.

Resource limits

In Compose these live under each service, for example mem_limit: 256m, cpus: 0.5 and read_only: true.

Scan for known vulnerabilities

Scanners compare every package in an image against public CVE databases. Run one locally and in CI (chapter 19), and rebuild on a schedule so base-image fixes reach you.

$ docker scout cves myapp:1.0          # built into Docker Desktop
$ trivy image myapp:1.0                 # open source, common in CI

Secrets

Environment variables (chapter 6) are configuration, not a vault. Know where each method leaks:

• Never put real secrets in ENV or ARG.
• A secret needed while building (a private registry token): a BuildKit secret mount, RUN --mount=type=secret,id=npmrc … with docker build --secret id=npmrc,src=.npmrc. It exists for that one step and is not saved in a layer.
• In production: the platform’s secret store (Kubernetes Secrets, Docker secrets, AWS Secrets Manager, Vault), usually mounted as files.

All together

FROM node:22 AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build && npm prune --omit=dev

FROM node:22-slim
WORKDIR /app
COPY --from=build --chown=node:node /app /app
# the official node images already contain a "node" user
USER node
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD node -e "fetch('http://localhost:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
CMD ["node", "dist/server.js"]

$ docker run -d --name api --restart unless-stopped \
    --memory 256m --cpus 0.5 --pids-limit 200 \
    --read-only --tmpfs /tmp --cap-drop ALL \
    -p 8080:3000 myapp:1.0

Try it yourself

1. Step 1 · Who are you inside?

   Most official images run as root unless told otherwise. --user overrides it at run time.

   $ docker run --rm alpine:3.20 id
   uid=0(root) gid=0(root)
   $ docker run --rm --user 1000:1000 alpine:3.20 id
   uid=1000 gid=1000

2. Step 2 · Watch a healthcheck

   The check runs every 5 seconds. After the first pass, docker ps shows (healthy).

   $ docker run -d --name hc --rm \
       --health-cmd 'wget -q -O /dev/null http://localhost/ || exit 1' \
       --health-interval 5s nginx:1.27-alpine
   $ sleep 6; docker ps --filter name=hc --format '{{.Names}}  {{.Status}}'
   hc  Up 6 seconds (healthy)
   $ docker stop hc

3. Step 3 · Hit a memory limit

   The shell tries to hold 100 MB in a 32 MB container. The kernel kills it.

   $ docker run --name oom --memory 32m alpine:3.20 sh -c 'x=$(head -c 100000000 /dev/zero | tr "\0" a)'
   $ docker inspect -f '{{.State.ExitCode}} oom={{.State.OOMKilled}}' oom
   137 oom=true
   $ docker rm oom

4. Step 4 · A read-only filesystem

   $ docker run --rm --read-only alpine:3.20 touch /hello
   touch: /hello: Read-only file system
   $ docker run --rm --read-only --tmpfs /tmp alpine:3.20 touch /tmp/hello && echo ok
   ok

Recap

• Start from the smallest base that works, and build in a separate stage.
• Add a user and switch to it with USER: root in a container is root on the kernel.
• HEALTHCHECK reports whether the app works, not just whether it runs.
• --memory, --cpus and --pids-limit are cgroup limits; exit 137 means the memory limit was hit.
• Scan images for CVEs, and keep secrets out of ENV, ARG and layers.

Quick check