Checkpoint Lab — Build Contexts, .dockerignore, Remote Contexts, Named Contexts, and Deterministic Build Inputs

1. Checkpoint mission and evidence contract

Build the same tiny application through two bounded input designs: a minimized default local context and a default context plus an explicit named documentation context. Record every input identity, builder/frontend baseline, BuildKit progress, image identity, and runtime output. Then modify an ignored unrelated file and prove the intended build dependency set does not change.

2. Preflight

mkdir -p ch08-checkpoint/{app,docs,noise,evidence}
cd ch08-checkpoint

docker context show | tee evidence/00-context.txt
docker version | tee evidence/01-version.txt
docker buildx version | tee evidence/02-buildx.txt
docker buildx inspect --bootstrap | tee evidence/03-builder.txt

Record limitations if a Buildx feature is unavailable. The mandatory path uses only local synthetic sources; the remote Git checksum form is documented as an optional compatibility exercise.

3. Create source-controlled inputs and a local immutable revision

printf 'application-v1\n' > app/message.txt
printf 'documentation-v1\n' > docs/readme.md
printf 'unrelated-v1\n' > noise/cache.tmp
printf 'FAKE_CREDENTIAL=not-a-secret\n' > .env

git init
git add app docs noise .env
git -c user.name='DevOps Academy' -c user.email='academy@example.invalid' commit -m 'checkpoint inputs'
SRC_SHA=$(git rev-parse HEAD)
printf 'source_commit=%s\n' "$SRC_SHA" | tee evidence/04-source-commit.txt
sha256sum app/message.txt docs/readme.md | tee evidence/05-input-hashes.txt

4. Design A: minimized default context

# .dockerignore
.git
.env
noise
evidence
docs

# local.Dockerfile
# syntax=docker/dockerfile:1
FROM busybox:1.37.0
WORKDIR /app
COPY app/message.txt ./message.txt
CMD ["cat", "/app/message.txt"]

docker buildx build --progress=plain --load \
  -f local.Dockerfile \
  --label devops-academy.lab=ch08-checkpoint \
  -t devops-academy-ch08-checkpoint:local . \
  2>&1 | tee evidence/06-local-build.txt

docker image inspect devops-academy-ch08-checkpoint:local \
  --format 'ImageID={{.Id}} RepoDigests={{json .RepoDigests}}' \
  | tee evidence/07-local-image.txt

docker run --rm devops-academy-ch08-checkpoint:local \
  | tee evidence/08-local-runtime.txt

5. Design B: explicit named documentation context

# named.Dockerfile
# syntax=docker/dockerfile:1
FROM busybox:1.37.0
WORKDIR /app
COPY app/message.txt ./message.txt
COPY --from=docs /readme.md ./docs/readme.md
CMD ["sh", "-c", "cat /app/message.txt; cat /app/docs/readme.md"]

docker buildx build --progress=plain --load \
  -f named.Dockerfile \
  --build-context docs=./docs \
  --label devops-academy.lab=ch08-checkpoint \
  -t devops-academy-ch08-checkpoint:named . \
  2>&1 | tee evidence/09-named-build.txt

docker image inspect devops-academy-ch08-checkpoint:named \
  --format 'ImageID={{.Id}} RepoDigests={{json .RepoDigests}}' \
  | tee evidence/10-named-image.txt

docker run --rm devops-academy-ch08-checkpoint:named \
  | tee evidence/11-named-runtime.txt

Design B intentionally has a different payload because it includes documentation. The checkpoint is not trying to force identical image IDs; it is proving explicit dependency boundaries and recorded source identity.

6. Prediction gate before changing unrelated data

Write down two predictions before the next command:

1. Changing noise/cache.tmp should not alter the default context seen by either build because noise is ignored.
2. Changing docs/readme.md should not affect Design A, but should affect Design B because docs is an explicit named input.

7. Prove unrelated ignored data cannot affect the intended result

printf 'unrelated-v2-%s\n' "$(date +%s)" > noise/cache.tmp

docker buildx build --progress=plain --load \
  -f local.Dockerfile -t devops-academy-ch08-checkpoint:local2 . \
  2>&1 | tee evidence/12-local-after-noise.txt

docker image inspect devops-academy-ch08-checkpoint:local2 --format 'ImageID={{.Id}}' \
  | tee evidence/13-local2-image.txt

docker run --rm devops-academy-ch08-checkpoint:local2 \
  | tee evidence/14-local2-runtime.txt

The application output must remain application-v1. Depending on builder metadata and output mode, compare exact local image IDs only when your environment makes that a stable expectation; the stronger proof is that the ignored noise is absent from context evidence and runtime payload while the build graph reuses unaffected steps as appropriate.

8. Prove the named input is a real dependency

printf 'documentation-v2\n' > docs/readme.md
sha256sum docs/readme.md | tee evidence/15-docs-v2-hash.txt

docker buildx build --progress=plain --load \
  -f named.Dockerfile --build-context docs=./docs \
  -t devops-academy-ch08-checkpoint:named2 . \
  2>&1 | tee evidence/16-named-after-doc-change.txt

docker run --rm devops-academy-ch08-checkpoint:named2 \
  | tee evidence/17-named2-runtime.txt

Now the output should contain documentation-v2. That contrast proves why named contexts improve causal reasoning: one independently identified source changed and only the build that consumes it changes behavior.

9. Optional remote Git checksum exercise

If network access and compatible tooling are available, choose a public disposable/test repository or your own reviewed source, record the expected commit, and use the structured Git URL-query form:

# Example shape only — substitute a reviewed repository/ref/commit.
docker buildx build \
  'https://github.com/ORG/REPO.git?tag=vX.Y.Z&subdir=docker&checksum=EXPECTED_COMMIT' \
  --progress=plain

If the checksum does not match the selected ref, the correct result is a failed build. Preserve that mismatch evidence. Do not weaken the check to make the build pass.

10. Evidence packet review

Your evidence/ directory should answer:

• Which Docker context, Engine/CLI, Buildx and builder handled the builds?
• What source-control commit and file hashes identify the local inputs?
• Which root/Dockerfile-specific ignore rules were in force?
• What did plain progress report for default and named contexts?
• Which source names/paths were supplied through --build-context?
• What local image identities resulted?
• Which unrelated change was proven irrelevant?
• Which named-source change was proven relevant?
• What remote Git checksum capability/limitations applied?

11. Exact cleanup

docker image rm \
  devops-academy-ch08-checkpoint:local \
  devops-academy-ch08-checkpoint:local2 \
  devops-academy-ch08-checkpoint:named \
  devops-academy-ch08-checkpoint:named2

docker image ls --filter label=devops-academy.lab=ch08-checkpoint
date -u +%Y-%m-%dT%H:%M:%SZ | tee evidence/18-finished-at.txt

Do not use broad prune. Keep the evidence directory and local Git metadata if you want the checkpoint to remain independently reviewable.

12. Operational review and Chapter 09 handoff

Chapter 08 established the build input boundary: default context, ignore processing, Dockerfile-specific precedence, remote source identity, and named contexts are all distinct build state. You can now prove which source bytes were eligible to affect an image rather than merely trusting the directory name or Git branch.

Chapter 09 moves inside the builder itself: BuildKit and buildx Architecture, Builders, Frontends, Progress, Outputs, and Modern Build Workflows. The context evidence created here becomes the input side of that deeper build-execution model.

Knowledge check

Official references and version notes

• Build context — authoritative behavior for local directories, Git repositories, tarballs, stdin/empty contexts, .dockerignore, Dockerfile-specific ignore files, Git URL queries/checksums, and named contexts.
• docker buildx build — --build-context, progress, outputs, metadata, and accepted named-context source types.
• Optimize cache usage — why a small context improves transfer and cache behavior and how .dockerignore reduces unnecessary input.
• Dockerfile reference — how COPY, ADD, and RUN --mount consume build inputs.
• Build best practices — source-control, cache, image, and reproducibility guidance.
• Docker Engine 29 release notes — current Engine baseline and fixes.
• Buildx releases — current Buildx feature/compatibility history.
• BuildKit releases — current BuildKit and built-in Dockerfile frontend releases.