Appendix A: Cheat Sheet
Everything important from Days 1–15 on a few pages. The number in
parentheses is the day on which you practiced it. When in doubt, the
Dockerfile reference at
docs.docker.com/reference/dockerfile/ and
docker build --check apply.
The model Dockerfile
The state the book works toward (Days 5, 7, 9, 10). For your own Go services it’s usually enough to swap paths and names.
# syntax=docker/dockerfile:1
# check=error=true
ARG GO_VERSION=1.27
# in production: pin @sha256:…, see Day 8
FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-alpine AS base
WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
COPY . .
FROM base AS test
RUN --mount=type=cache,target=/go/pkg/mod \
--mount=type=cache,target=/root/.cache/go-build \
go vet ./... && go test ./...
FROM base AS build
ARG TARGETOS TARGETARCH VERSION=dev
RUN --mount=type=cache,target=/go/pkg/mod \
--mount=type=cache,target=/root/.cache/go-build \
CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH \
go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" -o /out/notes-api .
FROM scratch AS final
ARG VERSION=dev REVISION=unknown CREATED=unknown
LABEL org.opencontainers.image.title="notes-api" \
org.opencontainers.image.version="${VERSION}" \
org.opencontainers.image.revision="${REVISION}" \
org.opencontainers.image.created="${CREATED}"
COPY --link --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --link --from=build /out/notes-api /notes-api
USER 65532:65532
EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=2s --start-period=5s --start-interval=1s \
CMD ["/notes-api", "healthcheck"]
STOPSIGNAL SIGTERM
ENTRYPOINT ["/notes-api"]Instructions
| Instruction | Rule of thumb | Day |
|---|---|---|
FROM img AS name |
base plus stage name; --platform=$BUILDPLATFORM for
cross-compiling |
1, 5, 7 |
ARG |
build time only; global before FROM, redeclare in the
stage; never secrets |
2, 11 |
ENV |
build and runtime, stored in the image config; never secrets | 2, 11 |
WORKDIR |
always absolute, creates the folder | 1 |
COPY |
files from context, stage or image; dependencies first | 1, 4, 5 |
ADD |
only for URLs/Git with --checksum, otherwise
COPY |
1 |
RUN |
new layer; mounts for cache and secrets | 1, 4, 13 |
USER |
numeric 65532:65532, before
ENTRYPOINT |
2, 9 |
EXPOSE |
documentation, opens nothing | 2 |
LABEL |
OCI annotations org.opencontainers.image.* |
2, 10 |
HEALTHCHECK |
exec form, own binary instead of curl; only the last one counts | 2, 15 |
STOPSIGNAL |
default SIGTERM; docker stop waits 10 s, then
SIGKILL |
2 |
ENTRYPOINT |
exec form, so the process is PID 1 and receives signals | 2 |
CMD |
default arguments for ENTRYPOINT |
2 |
SHELL |
changes the shell of the shell form, e.g. for
pipefail |
2 |
Header of every file: # syntax=docker/dockerfile:1, then
optionally # check=error=true or
# check=skip=<rule>;error=true (Day 9).
ENTRYPOINT and CMD
| ENTRYPOINT | CMD | What starts |
|---|---|---|
| – | ["notes-api"] |
notes-api |
["notes-api"] |
– | notes-api |
["notes-api"] |
["--help"] |
notes-api --help |
notes-api (shell form) |
anything | /bin/sh -c notes-api, CMD is ignored |
Shell form means: PID 1 is /bin/sh, and SIGTERM doesn’t
reliably reach the application. That’s why start scripts use
exec program "$@" (Day 2, Day 15).
COPY and ADD
| Option | Effect | From Dockerfile | Day |
|---|---|---|---|
--from=<stage> |
copy from a stage or a foreign image | – | 5, 7 |
--chown=65532:65532 |
set the owner without an extra RUN chown layer |
– | 9 |
--chmod=0755 |
set permissions; symbolic (u+x) only from 1.14 |
1.2 | 9 |
--link |
layer independent of its predecessor, better cache reuse | 1.4 | 7 |
--exclude=<pattern> |
leave out a pattern when copying | 1.19 | 3 |
--parents |
keep the directory structure of the source | 1.20 | 3 |
ADD --checksum=sha256:… |
download only with a matching checksum | 1.6 | 8 |
Build flags
| Flag | Effect | Day |
|---|---|---|
-t name:tag, -f file |
assign a name, different Dockerfile (-f - from
stdin) |
1, 15 |
--target test |
build only up to this stage | 5, 7 |
--build-arg K=V |
set an ARG; ends up in history and provenance | 2, 11 |
--progress=plain |
full output incl. CACHED and RUN
output |
4 |
--no-cache, --pull |
ignore the cache, pull the base image again | 4 |
--check |
build checks only, no build; exit ≠ 0 on findings | 9 |
-q |
print only the image ID | 1 |
--builder docker-lab |
use a dedicated BuildKit builder | 4, 7, 10 |
--platform linux/amd64,linux/arm64 |
multi-platform (only with --push or similar) |
7 |
--push, --load |
result to the registry or the local image store | 7, 10 |
--cache-to, --cache-from |
export/import cache, e.g. type=registry |
4 |
--secret id=…,src=… |
file as a build secret; ,env=VAR from the
environment |
13 |
--ssh default |
SSH agent for RUN --mount=type=ssh |
13 |
--sbom=true |
attach an SBOM attestation | 10 |
--provenance=mode=max |
detailed provenance; contains build arg values | 10 |
--label k=v |
set a label at build time | 10 |
Cache in the registry (Day 4):
docker buildx build --builder docker-lab \
--cache-to type=registry,ref=localhost:5001/notes-api:buildcache,mode=max \
--cache-from type=registry,ref=localhost:5001/notes-api:buildcache \
-t localhost:5001/notes-api:dev --push notes-apiReproducible builds (Day 10):
--build-arg SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct).
RUN mounts
| Type | Important options | Use | Day |
|---|---|---|---|
cache |
target, id, sharing
(shared, private, locked) |
Go, uv, npm caches | 4 |
bind |
source, target, from,
read-only by default |
files for just one step | 4 |
secret |
id, target, env,
required, mode (0400) |
tokens during the build | 13 |
ssh |
id (default), required |
private Git repos | 13 |
tmpfs |
target, size |
scratch space in memory | – |
# syntax=docker/dockerfile:1
FROM golang:1.27-alpine
WORKDIR /src
# Go: modules and build cache
RUN --mount=type=cache,target=/go/pkg/mod \
--mount=type=cache,target=/root/.cache/go-build \
--mount=type=bind,target=. \
go build -o /out/app .
# Secret as a file under /run/secrets/<id> (default path)
RUN --mount=type=secret,id=artifact_token,required=true \
test -s /run/secrets/artifact_token
# Secret as an environment variable for this step only (from Dockerfile 1.10)
RUN --mount=type=secret,id=artifact_token,env=ARTIFACT_TOKEN \
test -n "$ARTIFACT_TOKEN"More cache targets: uv /root/.cache/uv, npm
/root/.npm (Day 6). Secret mounts aren’t part of the cache
key: a new token value doesn’t rebuild the step (Day 13).
Build checks
docker build --check notes-api
docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=error=true" notes-api
docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=experimental=all" notes-api| Rule | Finds | Day |
|---|---|---|
SecretsUsedInArgOrEnv |
names like *_KEY, *_TOKEN in
ARG/ENV |
11 |
JSONArgsRecommended |
shell form for CMD/ENTRYPOINT |
2 |
FromAsCasing |
FROM … as … mixed with upper case |
9 |
UndefinedVar, UndefinedArgInFrom |
variables without a declaration | 2, 7 |
CopyIgnoredFile |
COPY of a file that .dockerignore
excludes |
3, 15 |
WorkdirRelativePath |
relative WORKDIR without an absolute one before it |
1 |
RedundantTargetPlatform |
--platform=$TARGETPLATFORM is redundant |
7 |
LegacyKeyValueFormat |
ENV K V instead of ENV K=V |
2 |
In addition, hadolint notes-api/Dockerfile with the
configuration .hadolint.yaml in the project folder (Day
9).
| Tool | checks | Day |
|---|---|---|
| hadolint | Dockerfile as text, RUN with ShellCheck |
9 |
| Build checks | Dockerfile during the build (BuildKit) | 9 |
| dockle | finished image (CIS Benchmark) | 9 |
| trivy | Dockerfile (config), folder (fs), image,
SBOM |
10, 11 |
| ShellCheck | shell scripts | 10 |
.dockerignore
# Comments only at the start of a line, never after a pattern
# The Dockerfile stays readable for BuildKit, but doesn't end up in the COPY
Dockerfile*
.dockerignore
.git
# all .env variants except the template
.env*
!.env.example
*.md
# ** matches any number of folder levels
**/node_modules
**/__pycache__
- Patterns are relative to the root of the context; the last matching line wins.
Dockerfile.distroless.dockerignorenext to the Dockerfile takes precedence over the general.dockerignore(Day 3).- An allowlist (
*plus!…) is strict, but easily forgets files (Day 15, Round 9). - A context spy shows what ends up in the context:
COPY . /ctxandRUN find /ctx -type fin a throwaway Dockerfile.
The secrets triangle
| File | Purpose | Into Git? | Day |
|---|---|---|---|
.env |
local values, including lab secrets | no | 12 |
.env.example |
template with all names, without values | yes | 12 |
.gitignore |
keeps .env, secrets/ out of the
repository |
yes | 12 |
.dockerignore |
keeps the same patterns out of the build context | yes | 3, 12 |
| Path into the image or container | Safe? | Proof | Day |
|---|---|---|---|
ARG / --build-arg |
✘ | docker history --no-trunc, provenance |
11 |
ENV |
✘ | docker image inspect, docker inspect |
11 |
COPY .env / RUN … && rm |
✘ | layer remains, docker save |
11 |
RUN --mount=type=secret |
✔ | not in history, not in a layer | 13 |
-e/env_file: at runtime |
partly | visible in docker inspect |
12, 14 |
file under /run/secrets/ + *_FILE |
✔ | only the path in docker inspect |
14 |
| Mechanism | Affects | Day |
|---|---|---|
.env next to compose.yaml |
interpolation of ${VAR} in the Compose file |
12 |
env_file: |
environment in the container | 12 |
docker run --env-file |
environment in the container | 12 |
docker compose config |
shows resolved values – watch out, leak | 12 |
Rule of thumb: what was once in a layer stays in there. A leaked key gets rotated, not just deleted (Day 11, Day 15).
Compose secrets
services:
notes-api:
build:
context: notes-api
secrets:
- artifact_token # build secret (Day 13)
environment:
NOTES_API_KEY_FILE: /run/secrets/notes_api_key
secrets:
- notes_api_key # runtime secret (Day 14)
ports:
- "127.0.0.1:8080:8080"
secrets:
artifact_token:
environment: ARTIFACT_TOKEN # value from the shell environment
notes_api_key:
file: ./secrets/notes_api_key.txt # file is listed in .gitignoreRuntime secrets live in the container under
/run/secrets/<name>. Rotating without a rebuild:
change the file,
docker compose up -d --force-recreate notes-api (Day
14).
Runtime hardening
docker run -d --name notes-api \
--read-only --tmpfs /tmp \
--cap-drop ALL --security-opt no-new-privileges \
--user 65532:65532 \
-e NOTES_API_KEY_FILE=/run/secrets/notes_api_key \
-v "$PWD/secrets/notes_api_key.txt:/run/secrets/notes_api_key:ro" \
-p 127.0.0.1:8080:8080 notes-api:tag14Ports only on 127.0.0.1; --init only if the
image has no signal handling of its own (Day 2, Day 9).
Inspection
# Layers and origin (Day 1, 11)
docker history --no-trunc --format '{{.CreatedBy}}' notes-api:tag14
docker image inspect --format '{{json .Config}}' notes-api:tag14 | jq .
docker image inspect --format '{{.Config.User}} {{.Os}}/{{.Architecture}}' \
notes-api:tag14
docker image ls --digests localhost:5001/notes-api
# Running container (Day 2, 9, 14)
docker inspect --format '{{.State.Health.Status}}' notes-api
docker inspect --format '{{json .State.Health.Log}}' notes-api | jq -r '.[-1].Output'
docker inspect --format '{{json .Config.Env}}' notes-api
docker top notes-api
docker logs notes-api
# Registry, platforms, attestations (Day 7, 8, 10)
docker buildx imagetools inspect localhost:5001/notes-api:tag10
docker buildx imagetools inspect localhost:5001/notes-api:tag10 \
--format '{{json .SBOM}}'
docker buildx imagetools inspect localhost:5001/notes-api:tag10 \
--format '{{json .Provenance}}'
# Scanners and linters (Day 9, 10, 11)
hadolint notes-api/Dockerfile
trivy config --severity HIGH,CRITICAL --exit-code 1 notes-api/Dockerfile
trivy image --severity HIGH,CRITICAL --exit-code 1 notes-api:tag14
trivy image --scanners secret notes-api:tag14
trivy fs --scanners secret .
dockle --exit-code 1 --exit-level warn notes-api:tag14 # exceptions: .dockleignore
shellcheck -S warning ~/docker-lab/code/tag*/*.sh # directives: # shellcheck …
# Git and context (Day 3, 12)
git check-ignore -v .env
git status --ignored --short
docker system dfFailure patterns
| Symptom | Cause | Fix |
|---|---|---|
| image over 1 GB | compiler and caches in the final image | multi-stage, scratch/distroless (5) |
| every build downloads everything again | COPY . . before the dependencies |
lockfiles first, cache mount (4) |
| key in history/config | ARG/ENV with a secret |
secret mount, rotate (11, 13) |
.env in the image |
missing .dockerignore, COPY . . |
.dockerignore, copy selectively (3) |
| runs as root | no USER |
USER 65532:65532 (9) |
docker stop takes 10 s |
shell as PID 1 | exec form, exec in the script (2) |
exec format error |
wrong architecture in the binary | TARGETOS/TARGETARCH (7) |
x509: … unknown authority |
CA bundle missing in scratch |
copy ca-certificates.crt (5) |
"/go.sum": not found |
.dockerignore too greedy |
exception !go.sum, --check (3) |
unhealthy for no reason |
healthcheck needs shell/curl | exec form with own binary (2) |