Skip to content
Hands-on IT IT Drills

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-api

Reproducible 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.dockerignore next 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 . /ctx and RUN find /ctx -type f in 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 .gitignore

Runtime 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:tag14

Ports 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 df

Failure 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)