Dockerfile best practices: size, caching, and non-root security

Before anything else: docker build sends the entire build context (every file in the directory, by default) to the Docker daemon before it even reads the Dockerfile. Without a .dockerignore, that includes node_modules, .git, local .env files, and build artifacts — slowing every build and risking a genuine secret leak if a .env file ever gets COPY .'d into an image layer.

This mirrors .gitignore in spirit: keep things that don't belong in the image out of the build context entirely, rather than trusting every COPY instruction to be written carefully.

There's no universally "right" answer — alpine is the common default for size, but a native dependency that only builds against glibc can turn "smaller image" into "broken build," so test the actual base image against your dependency tree rather than assuming.

Every RUN, COPY, and ADD instruction creates a layer, and Docker reuses cached layers only up to the first instruction whose input changed. The practical rule: order instructions from least likely to change to most likely to change.

The only difference is instruction order, but the second version turns a 2-second rebuild into a 45-second one on every single code change, because COPY . . runs first and its changed content invalidates every layer after it — including the expensive npm ci.

Each RUN is a layer, and each layer adds a small amount of image size even for things later deleted in a different layer:

This only matters for instructions that add and then remove data in the same conceptual step (package manager caches, temp build files) — don't over-apply it to instructions that have nothing to clean up, since collapsing everything into one giant RUN just kills readability and cache granularity for no benefit.

By default, a container's process runs as root inside the container. If an attacker finds a remote code execution vulnerability in the app, root inside the container is a meaningfully worse starting point than an unprivileged user — especially combined with any container-escape vulnerability, where root-in-container can become root-on-host.

Official images increasingly ship a pre-made unprivileged user for exactly this (node on the node images, for example) — check the base image's documentation before hand-rolling one.

A secret passed via ARG or ENV and used in a RUN command is not removed by a later RUN rm — it's already baked into an earlier, still-present layer, extractable with docker history or by anyone who can pull the image.

The secret exists only for the duration of that one RUN instruction's execution and is never committed to any layer — a fundamentally different guarantee than "delete it in a later step."