Containers

A container image is the unit you build, test and ship. The same image runs on a laptop, in CI and in production, so its flaws travel everywhere. These rules apply to Docker, Podman and any runtime that follows the OCI image standard.

Two related rules live elsewhere. Run the tests inside the container build, and make builds repeatable.

Required

• Pin each base image by digest

  Required

  Name every base image by version and digest, never by a moving tag such as latest. Choose the smallest image that runs the app.

• Keep build tools out of the runtime image

  Required

  Build in one stage and copy only the finished app into a clean final stage. Compilers, test tools and development packages never reach the image you ship.

• Run containers as a user without root

  Required

  Switch to a user without root with USER before the app starts. Give that user write access only to the folders the app writes.

• Never give a container control of the host

  Required

  Never run an app container with --privileged, the host's network or process namespace, or the container engine's socket mounted inside.

• Send only the files the build needs

  Required

  Keep a .dockerignore that leaves out dependencies, build output, version control, local data and every secret file.

• Pass build secrets as mounts instead of layers

  Required

  Give the build a token or key only through a secret mount. Never through ARG, ENV, or a copied file.

• Let the main process receive stop signals

  Required

  Start the app in exec form, so it receives the stop signal itself. Add a small init process that forwards signals and reaps child processes.

• Scan every image before it ships

  Required

  Scan each built image for known holes in CI, and fail the build on high or critical ones that have a fix.

Recommended

• Make the container file system read-only

  Recommended

  Run containers with a read-only root file system. Mount a volume for data and a tmpfs for scratch files.

• Declare a health check in the image

  Recommended

  Give every service image a HEALTHCHECK that calls the app's own health address.

• Run one process per container

  Recommended

  Give each container one main process, and read every setting from the environment.

• Run the same images locally with Compose

  Recommended

  Describe the local setup in one Compose file that uses the production images and versions, so the app runs the same way on every laptop.