In this article 8 sections
- 1. Start from a small, trusted base image
- 2. Build in one stage, ship from another
- 3. Keep the build context clean with .dockerignore
- 4. Pin the base image, then let a bot update it
- 5. Put apt-get update and install in one layer
- 6. Pass secrets at build time, never copy them in
- 7. Run as a non-root user
- Put together
Most Dockerfiles work on the first try. The problems arrive later: an image that is two gigabytes, a build that changes without anyone touching it, a token left in a layer. Docker's own build guide covers each of these. This checklist takes the seven habits from it that prevent the most trouble, in the order you meet them when writing a Dockerfile.
1. Start from a small, trusted base image
Docker's guide calls the base image the first step towards a secure image, and gives two tests: it comes from a trusted source, and it is small. On Docker Hub, look for the Docker Official Image and Verified Publisher badges. A smaller base downloads faster and, as the guide puts it, minimizes the number of vulnerabilities introduced through the dependencies.
The same reasoning applies to what you add on top. The guide's example is blunt: a database image does not need a text editor.
2. Build in one stage, ship from another
A multi-stage build uses more than one FROM. The first stage holds compilers, package caches and build tools. The last stage copies in only the finished result with COPY --from. The final image then contains the files needed to run the application and nothing that was only needed to build it. Stages that do not depend on each other can also build in parallel.
3. Keep the build context clean with .dockerignore
Everything in the build directory can end up in the image through a broad COPY . .. A .dockerignore file excludes files from the build using patterns similar to .gitignore. A reasonable start:
.git
.env
node_modules
*.md
Listing .env here is the cheapest protection against copying local secrets into an image by accident.
4. Pin the base image, then let a bot update it
Image tags are mutable. FROM alpine:3.21 resolves to whatever patch release the tag points to on the day you build, so the same Dockerfile can produce a different image three months later. To get the same base every time, pin the digest as well:
FROM alpine:3.21@sha256:<digest>
The guide is clear about the cost: a pinned digest also opts you out of automatic security fixes. Its answer is to automate the update instead of leaving the tag loose. GitHub Dependabot with package-ecosystem: "docker" opens a pull request when the base image changes, which gives you both control and a record of when it changed. docker scout recommendations lists available base image updates from the command line.
Pinning is not a reason to stop rebuilding. Images are snapshots, so rebuild regularly, and use docker build --pull to fetch a fresh base when you are not pinning by digest.
5. Put apt-get update and install in one layer
On Debian and Ubuntu images, always combine the two commands in a single RUN:
RUN apt-get update && apt-get install -y --no-install-recommends \
curl \
git \
&& rm -rf /var/lib/apt/lists/*
The reason is the build cache. If apt-get update sits in its own RUN, Docker caches that layer. When you later add a package to the install line, the cached update is reused and the install can fetch outdated package versions or fail. One layer means the package list is refreshed whenever the package set changes.
--no-install-recommends skips optional packages, and removing /var/lib/apt/lists keeps the package index out of the image. Sorting the packages alphabetically makes later changes easier to review.
6. Pass secrets at build time, never copy them in
Docker's documentation says build arguments and environment variables are inappropriate for secrets, because they persist in the final image. A file added with COPY ends up in a layer as well. Build secrets avoid both. Pass the secret on the command line:
docker build --secret id=aws,src=$HOME/.aws/credentials .
Then mount it only for the instruction that needs it:
RUN --mount=type=secret,id=aws \
AWS_SHARED_CREDENTIALS_FILE=/run/secrets/aws \
aws s3 cp ...
By default the secret appears as a file at /run/secrets/<id> inside the build container for that one RUN. A secret can also come from an environment variable: docker build --secret id=API_TOKEN . mounts the value of API_TOKEN at /run/secrets/API_TOKEN.
7. Run as a non-root user
If the service does not need privileges, create a user and switch to it. The guide's example:
RUN groupadd -r postgres && useradd --no-log-init -r -g postgres postgres
Follow it with a USER instruction. Two notes from the guide: assign an explicit UID and GID if other systems depend on them, because the automatically assigned numbers can change between rebuilds, and avoid installing sudo, which behaves unpredictably with terminals and signals inside containers.
Put together
A Python service that applies the list:
# syntax=docker/dockerfile:1
FROM python:3.13-slim AS build
RUN python -m venv /opt/venv
RUN --mount=type=bind,source=requirements.txt,target=/tmp/requirements.txt \
/opt/venv/bin/pip install --no-cache-dir --requirement /tmp/requirements.txt
FROM python:3.13-slim
RUN groupadd -r app && useradd --no-log-init -r -g app app
WORKDIR /app
COPY --from=build /opt/venv /opt/venv
COPY . .
USER app
ENTRYPOINT ["/opt/venv/bin/python", "main.py"]
The dependency install uses a bind mount for requirements.txt, which the guide recommends over COPY for files needed by a single RUN. ENTRYPOINT sets the main command; add a CMD after it if the program takes default flags. For a production image, add the digest from step 4 to both FROM lines.
Containers built this way are easy to throw away and replace, which is the property the guide asks for when it says containers should be as ephemeral as possible.
Sources
This article reflects public information available when it was written. Versions, defaults and prices can change; check the linked official documentation.
The individual instructions are quoted from Docker's documentation as read on November 12, 2026. The combined Dockerfile at the end was not built for this article, because no Docker daemon was available where it was written. Written for this site with AI assistance, from the sources above. For errors or additional information, please request a correction. Editorial policy