A Dockerfile for one binary

Two stages, one file copied, one non root user. The image contains the program and almost nothing else.

The build produces a static binary, so the runtime image does not need a Go toolchain, a shell script, or the source. Two stages keep those apart.

A dark placeholder card reading One binary image

The file

FROM golang:1.27-alpine AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/web ./cmd/web

FROM alpine:3.22
RUN adduser -D -H -u 10001 app
COPY --from=build /out/web /app/web
USER app
EXPOSE 8080
ENV ADDR=:8080
ENTRYPOINT ["/app/web"]

A dark placeholder panel showing the two stages

The lines that matter

Line Why
COPY go.mod go.sum before COPY . . The module layer is cached until dependencies change
CGO_ENABLED=0 A static binary, so the runtime image needs no C library
-trimpath -ldflags="-s -w" No local paths in the binary, no debug tables
USER app The process does not run as root
ENTRYPOINT ["/app/web"] No shell wrapper, so signals reach the program

The order of the two COPY instructions is the difference between a rebuild that takes a moment and one that downloads every dependency again.

Why not scratch

scratch is smaller, but it has no timezone data and no CA certificates. The site needs neither today. Alpine costs a few megabytes and keeps the door open for a curl during a debug session on the host.

The smallest image is not always the best one. The image you can still inspect at 2am is worth a few megabytes.

Building and running

podman build -t personal-website .
podman run --rm -p 127.0.0.1:8080:8080 \
  -e SITE_URL=https://example.com \
  personal-website

-p 127.0.0.1:8080:8080 publishes on loopback only. A tunnel or a reverse proxy on the same host reaches it; nothing else does.

What is not in the image

No database client, no package manager cache, no source, no .git. If a future change needs one of those at runtime, that is a signal the design moved, not a reason to add a line here.

Back to all posts