Write a Dockerfile: FROM, COPY, RUN, CMD and multi-stage builds

A Dockerfile is a plain text recipe. docker build reads it top to bottom and runs each instruction in a temporary container, saving the result as a new image layer. Understanding that each line is a layer explains both why builds can be fast (unchanged layers are reused from cache) and why images can get bloated (files deleted in a later layer still exist in an earlier one).

A first Dockerfile

FROM python:3.13-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000
CMD ["python", "app.py"]

• FROM picks the base image. Always use a specific tag such as 3.13-slim; latest changes under you.
• WORKDIR sets the directory for the following instructions and creates it if needed.
• COPY src dest copies files from the build context (the directory you pass to docker build) into the image. ADD does the same plus URL downloads and tar extraction; prefer COPY unless you need those.
• RUN executes a command at build time and saves the result as a layer. Combine related commands with && so they share one layer.
• EXPOSE documents the port the program listens on. It does not publish anything; -p at run time does.
• CMD is the default command when a container starts. The JSON array form avoids a shell wrapper and lets signals such as Ctrl+C reach the process.

Build and run it:

docker build -t myapp:1.0 .
docker run --rm -p 8000:8000 myapp:1.0

Order instructions for the cache

Docker reuses a cached layer only if the instruction and all layers before it are unchanged. For COPY, that means the copied files must be identical. The example above copies requirements.txt and installs dependencies before copying the rest of the source. Editing app.py then only invalidates the final COPY, and the slow pip install layer comes from cache. Put the things that change least at the top.

Keep files out with .dockerignore

Everything in the build context is sent to the daemon and is available to COPY . .. A .dockerignore file next to the Dockerfile excludes what should never end up in the image:

.git
.venv
__pycache__
node_modules
*.log
.env

CMD vs ENTRYPOINT

CMD is replaced entirely if you pass a command to docker run, for example docker run myapp:1.0 python -m pytest. ENTRYPOINT is always run and anything you pass becomes its arguments. The two combine: use ENTRYPOINT for the fixed program and CMD for default arguments.

ENTRYPOINT ["python", "manage.py"]
CMD ["runserver", "0.0.0.0:8000"]

Do not run as root

By default the process inside a container runs as root. Create a user in the image and switch to it after the installation steps that need root:

RUN useradd --create-home --shell /bin/bash appuser
USER appuser

Multi-stage builds

Compiled languages need a compiler and build tools, but the finished program does not. A multi-stage build uses one FROM to build and a second, smaller FROM for the final image, copying only the result across. The build tools never appear in the image you ship.

FROM golang:1.27 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /out/server .

FROM gcr.io/distroless/static-debian12
COPY --from=build /out/server /server
USER nonroot
EXPOSE 8080
ENTRYPOINT ["/server"]

The same pattern works for Node.js front ends (build with node, serve with nginx) and for Java (build with a JDK image, run on a JRE image). docker build --target build -t myapp:build . stops after the first stage when you want to debug it.

Checking the result

docker image ls myapp
docker history myapp:1.0
docker run --rm myapp:1.0 id

history shows each layer with its size, which is the quickest way to spot an instruction that made the image unexpectedly large.

Official documentation

• Dockerfile reference
• Building best practices
• Multi-stage builds