Docker for Reproducible AI

A teammate clones access-rag, finds the three eval rows and scripts/score_access_requests.py, and still can't reprint 0.667. Their Python version, OS packages, or filesystem permissions differ from yours. Git carried the files. It didn't pin how they run.

The scorer compares a predicted label with an expected label on each row. Two matches out of three give 2/3, displayed as 0.667. Nothing about that calculation should depend on a teammate's Python setup.

Docker packages Python, its dependencies, and application files in a container image, the stored artifact produced by docker build. Its filesystem is assembled from reusable layers. A container is an isolated instance of that image, created by docker run. Ours runs one scorer process; other applications may start child processes too.

When the scorer exits, --rm removes the stopped container and its writable layer. The image remains available for another run.

The kernel is the operating system component that manages processes, memory, and devices. A Linux image packages application code and user-space tools, including Python and Debian libraries, but no kernel. Containers share the Linux kernel of the machine running Docker Engine. With Docker Desktop's Linux containers, that machine is a Linux virtual machine (VM), so a Mac container uses the VM's Linux kernel.^{[1]Reference 1Bind mountshttps://docs.docker.com/engine/storage/bind-mounts/}

Use the access-rag/ directory from Git, Shell, and Linux for Reproducible AI. Run the commands in a Bash-compatible terminal with Docker Engine running, or Docker Desktop set to Linux containers. On Windows, use a WSL terminal. docker version should show both a client and a server; a client alone can't build or run an image.

View larger

Where each input lives

The scorer needs Python and its own files every time. The eval data may change between runs, and future API keys shouldn't travel with the image at all. A Dockerfile is the build recipe; it chooses which inputs become part of the image. The rest arrive when a container starts:

Don't solve every placement with COPY. A bind mount exposes a specific host path inside a container. A named volume is storage Docker manages, which suits caches or state that should outlive one container without depending on a teammate's directory layout.

Build-time and run-time inputs also have different lifetimes. Stable inputs become image layers. Run-specific data and configuration join only when a container starts, and Docker can reuse an earlier layer when its inputs didn't change.^{[2]Reference 2Building Best Practiceshttps://docs.docker.com/build/building/best-practices/#pin-base-image-versions}

Suppose you fix a line in the scorer but leave its packages alone. Docker should reuse the installed packages and rebuild only the application-dependent steps. That reuse is the build cache:

View larger

Edit the scorer and the dependency layer can stay cached. Change requirements.txt and its installation must run again, so the stable file goes in first. The Dockerfile below separates installation and execution into stages while preserving that dependency order.

Start with .dockerignore

The build context is the first boundary. If access-rag/ contains a model cache, a local index, and .env, docker build . can make all of them available to the builder before the Dockerfile chooses what to copy. Which paths should never cross that boundary?

Create .dockerignore at the root of access-rag/, next to .gitignore:

# .dockerignore - keep the build context tiny and secret-free
.env*
*.pem
secrets/
.git/
.github/
.venv/
.docker-lab/
__pycache__/
*.py[cod]
*.egg-info/
node_modules/
models/
*.gguf
*.safetensors
*.bin
chroma/
faiss_index/
*.db
runs/
eval_cache/
wandb/
mlruns/
.DS_Store
.idea/
.vscode/
*.swp

Docker removes matching paths before it sends the build context to the builder. Without that filter, .env, cached model files, local indexes, notebooks, and virtualenvs can reach a local or remote builder even when the Dockerfile never meant to copy them. A later broad COPY . /app can also bake them into a layer.^{[2]Reference 2Building Best Practiceshttps://docs.docker.com/build/building/best-practices/#pin-base-image-versions}

Build context and image contents aren't the same thing. Context is everything the builder is allowed to read; COPY and ADD decide which of those files become layers. If a path matches .dockerignore, it never enters the context. Now choose which of the remaining files the scorer actually needs.

Reuse the scorer you already tested

The previous chapter committed scripts/score_access_requests.py and eval/access_requests.jsonl. Package those same files so the container result can be compared with the Git check. A second scorer would add another possible cause of a changed result.

The Git scorer falls back to assets/access_requests.jsonl when eval/ is missing. Copying eval/ into the image is enough for the primary path, so you don't need assets/ in the image. requirements.txt can stay empty until the scorer gains third-party packages.

Check that you're in the project root, create the empty dependency file if needed, and run the scorer once outside Docker:

test -f scripts/score_access_requests.py
test -f eval/access_requests.jsonl
touch requirements.txt
python3 scripts/score_access_requests.py

Eval rows: 3
Exact-match accuracy on tiny fixture: 0.667 (2/3)
Gate passed. You may commit.

That output is the baseline the image must preserve. The scorer and the fixture stay as they are. The image has to pin which Python actually runs them, so a teammate's laptop stops being part of the result.

Give the scorer its own Python environment

Start with a CPU image. The three-row scorer doesn't need a GPU, so prove the container contract on an ordinary laptop before adding NVIDIA runtime setup.

Each FROM starts a build stage, a separate filesystem based on the named image. The first stage installs packages into a virtual environment, a directory containing a Python environment isolated from other packages. The second copies that environment and runs the scorer. This two-stage pattern becomes useful when installation needs compilers or other tools that the running application doesn't need. Our empty dependency file doesn't need those tools yet, so two stages aren't inherently smaller here.

Create this Dockerfile:

# syntax=docker/dockerfile:1
# Tag is fine for learning. To fix base-image bytes, pin both stages by digest:
# FROM python:3.12-slim-trixie@sha256:<verified-digest> AS builder
FROM python:3.12-slim-trixie AS builder

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1

RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

COPY requirements.txt /tmp/requirements.txt
# Empty requirements are fine here. Once packages appear, export every
# transitive dependency with hashes or use a lock-aware frozen install.
RUN python -m pip install --no-cache-dir --require-hashes -r /tmp/requirements.txt

FROM python:3.12-slim-trixie AS runtime

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PATH="/opt/venv/bin:$PATH"

RUN useradd --create-home --no-log-init --user-group --uid 10001 --shell /usr/sbin/nologin appuser

WORKDIR /app

COPY --from=builder /opt/venv /opt/venv
COPY --chown=appuser:appuser scripts/score_access_requests.py scripts/score_access_requests.py
COPY --chown=appuser:appuser eval/ eval/

USER appuser

ENTRYPOINT ["python", "scripts/score_access_requests.py"]

Read the runtime stage from top to bottom. WORKDIR /app sets the directory for later relative paths. COPY --from=builder transfers the installed environment, while the next two COPY instructions bring in the scorer and fixture. USER appuser selects the identity for the running process. ENTRYPOINT supplies its default command, so docker run doesn't need to repeat the Python filename.

Both stages use the same base image and /opt/venv path to keep the copied environment compatible. If later packages need shared OS libraries, those libraries must also exist in the runtime stage. Copying a virtual environment alone doesn't copy every system dependency.

Here the runtime stage starts from python:3.12-slim-trixie, so it declares its own PATH, bytecode, and buffering settings. It doesn't inherit the builder's ENV settings. A stage based on FROM builder would inherit them. Likewise, installing a compiler in this builder doesn't install it in this runtime. COPY --from=builder transfers only the selected files.

COPY defaults to root ownership. Root-owned files with world-readable permissions can still be read by appuser, but COPY --chown=appuser:appuser makes ownership explicit and avoids permission failures when files have restrictive modes or the application later needs to write its own files.

The official Python image manifest maps python:3.12-slim-trixie to the Python 3.12 line on Debian 13 (trixie).^{[3]Reference 3Official Python Image Manifesthttps://github.com/docker-library/official-images/blob/master/library/python[4]Reference 4Debian Trixie Release Informationhttps://www.debian.org/releases/trixie/} That constrains the Python minor line and Debian release, but it doesn't pin exact bytes. Image tags are mutable, so a later rebuild can pick up a new Python patch or rebuilt OS packages.^{[2]Reference 2Building Best Practiceshttps://docs.docker.com/build/building/best-practices/#pin-base-image-versions}

Dependency pins need the same care. package==1.2.3 fixes a version, but an installer may still choose among wheels (prebuilt packages) and source archives. A hash identifies an allowed downloaded artifact. For a release, export all dependencies, including dependencies of dependencies, with hashes and keep --require-hashes. Alternatively, use a package-manager lockfile with its frozen install command. An empty requirements.txt passes because there are no packages to verify. Adding an unhashed package makes the build fail instead of silently weakening the policy.^{[5]Reference 5Secure Installshttps://pip.pypa.io/en/stable/topics/secure-installs/}

A lockfile affects this image only if its install step consumes it. Merely copying a future uv.lock into the context won't change this pip command. Keep one reviewed dependency source for the image, or explicitly export the lock to the hashed requirements this Dockerfile reads. Hashing a source archive also doesn't lock the tools that compile it. For a wheel-only release, --only-binary=:all: rejects source builds, but it will fail when no compatible wheel exists for the target platform.^{[5]Reference 5Secure Installshttps://pip.pypa.io/en/stable/topics/secure-installs/}

python:3.12-slim-trixie is a multi-platform tag. Docker normally selects the variant that matches the host. An Apple Silicon laptop can build linux/arm64 while an x86 CI worker builds linux/amd64. Those are compatible recipes, not identical image bytes. Predict which architecture your release needs, inspect the available variants, then set the deployment target:

docker buildx imagetools inspect python:3.12-slim-trixie
docker build --platform linux/amd64 -t access-rag:local .

For a fixed release, copy a verified sha256:... digest from the inspection into both FROM lines. A digest identifies content, unlike a tag that can be reassigned. A multi-platform index digest fixes a set of platform variants; a platform manifest digest fixes one variant. Keep --platform in the build command to select the intended architecture. Emulating linux/amd64 on an Arm laptop can be much slower than a native build, especially when packages compile code.^{[6]Reference 6Multi-platform buildshttps://docs.docker.com/build/building/multi-platform/}

Once that target is explicit, cache behavior becomes easier to reason about. A package change invalidates the dependency layer and later layers; editing scripts/score_access_requests.py won't force a full package reinstall, because the Dockerfile installs requirements first.

Build, run, and inspect the artifact

From the project root, check the Dockerfile and then build the artifact. The first command reports Dockerfile findings without producing an image; the second creates the tagged image. The final . selects the current directory as the build context, and -t gives the image its local name.

docker build --check .
docker build -t access-rag:local .

docker build --check exits nonzero when a check reports a finding. A regular build can report those findings as warnings, so running the check separately makes the policy explicit.^{[7]Reference 7Checking your build configurationhttps://docs.docker.com/build/checks/}

Run the image without any host mount first. Will --read-only break the scorer? It only reads the fixture, and the Dockerfile disables Python bytecode writes, so making the container's root filesystem read-only should preserve the result:

docker run --rm --read-only access-rag:local

Expected output:

Eval rows: 3
Exact-match accuracy on tiny fixture: 0.667 (2/3)
Gate passed. You may commit.

Inspect the artifact as well as its stdout:

docker image inspect access-rag:local \
  --format 'platform={{.Os}}/{{.Architecture}} user={{json .Config.User}} entrypoint={{json .Config.Entrypoint}}'

The platform should match the build target, the configured user should be appuser, and the entrypoint should name the scorer. A successful --read-only run shows that this execution can finish without writing to its root filesystem. Different inputs or a later workload may require writable storage. PYTHONDONTWRITEBYTECODE=1 keeps Python from trying to write .pyc files when that filesystem is read-only.

Inspect the process identity separately from the host user who launches Docker. Overriding the entrypoint lets us run one diagnostic command without changing the image:

docker run --rm --read-only --entrypoint id access-rag:local

Expect uid=10001(appuser). The group number is chosen when useradd creates the group, so don't assume it also equals 10001. On a normal Linux Engine without user-namespace remapping, numeric ownership controls access to bind-mounted files. Rootless engines and Docker Desktop can map identities differently. The mounted-path check belongs to that host setup.

USER appuser limits the application process. It doesn't reduce the authority of whoever controls Docker's daemon. Access to a normal rootful daemon can grant host-level privileges, and a container with a writable bind mount can alter the permitted host files. Don't mount the Docker socket or unrelated host directories into this scorer. The application user, daemon access, and mount permissions are separate boundaries.^{[8]Reference 8Docker securityhttps://docs.docker.com/engine/security/}

The printed score is rounded for humans. Keep the gate on integer counts, the same rule the Git scorer uses (correct * 3 >= total * 2), not equality to the decimal 0.667. This tiny check makes that distinction visible:

matches, total = 2, 3
score = matches / total

assert 0 <= matches <= total
print(f"score={score:.3f} ({matches}/{total})")
print("gate_passed:", matches * 3 >= total * 2)

score=0.667 (2/3)
gate_passed: True

A bind mount obscures the copied eval

A passing run confirms that the image can read its baked fixture. Editing the host's eval/ won't change those copied files: they're a snapshot from build time. A bind mount lets us supply new data without rebuilding the scorer.

Run the image against host data:

docker run --rm \
  --read-only \
  --mount type=bind,source="$PWD/eval",target=/app/eval,readonly \
  access-rag:local

A bind mount at /app/eval obscures the image's copied files for that run. Docker doesn't merge the two directories. --mount is the better default here because it fails when the host source path is missing. -v can silently create a missing source as an empty directory. If the score changes, compare the mounted fixture with the committed one before changing the image.^{[1]Reference 1Bind mountshttps://docs.docker.com/engine/storage/bind-mounts/}

The source path must exist where the Docker daemon runs. Docker Desktop handles sharing your local project into its Linux virtual machine. With a remote daemon or another VM setup, a path that exists in your terminal may still be unavailable to Docker; check file sharing before changing the scorer.

The mount is read-only from inside the container, but file permissions still apply. appuser must be able to traverse the mounted directories and read the fixture. For writable data, a named volume removes the dependency on a particular host path, not the need for correct ownership. Initialize its directory for the application's user, or document the numeric user and group IDs (UID/GID) required on a bind-mounted path. Switching to root hides that setup problem.^{[9]Reference 9Volumeshttps://docs.docker.com/engine/storage/volumes/}

Turn one boundary into a failure

Test the mount behavior without renaming or deleting the committed fixture. Before running the command, predict which directory Python will see at /app/eval. Will a read-only mount preserve access to the copied fixture?

Create an empty scratch directory and mount it over /app/eval:

mkdir -p .docker-lab/empty-eval
docker run --rm --read-only \
  --mount type=bind,source="$PWD/.docker-lab/empty-eval",target=/app/eval,readonly \
  access-rag:local

The scorer should fail with a missing-file error and a nonzero exit status. Because the source directory exists, Docker can create the mount. Python then looks for access_requests.jsonl and can't see the baked copy underneath it. The image doesn't contain the scorer's assets/ fallback either. Rerun without the mount and 0.667 (2/3) should return without rebuilding anything.

The error names the fallback path because the scorer tries it after failing to find eval/access_requests.jsonl:

ERROR: assets/access_requests.jsonl missing; commit the eval fixture

View larger

Compare that failure with other small changes:

The distinction saves a rebuild: a missing host path is a mount problem, while a missing file inside an existing mount is an input-data problem.

Check in one Compose file

For one service, docker run is enough. As soon as the project adds a vector database, API, worker, or model cache, one checked-in Compose file gives each engineer the same starting command and mount policy. Add only the scorer that exists today.

Start with a runnable compose.yaml for the scorer:

services:
  scorer:
    build:
      context: .
      dockerfile: Dockerfile
    image: access-rag:local
    read_only: true
    volumes:
      - type: bind
        source: ./eval
        target: /app/eval
        read_only: true
        bind:
          create_host_path: false

create_host_path: false preserves the missing-directory failure we chose with docker run --mount. Compose otherwise creates a missing bind source directory by default. read_only: true on the service protects its root filesystem; the second read_only protects the separate data mount.^{[10]Reference 10Compose service referencehttps://docs.docker.com/reference/compose-file/services/}

Validate the file before running it:

if docker compose version >/dev/null 2>&1; then
  docker compose config --quiet
  docker compose run --build --rm scorer
else
  echo "Docker Compose plugin missing. Install docker-compose-plugin before using compose."
fi

Docker Desktop includes Compose. Some Linux Engine installs need the docker-compose-plugin package first; follow Docker's plugin installation instructions. If docker compose version is unknown, the Dockerfile still works through docker run, but the Compose workflow isn't installed yet.

Omit the obsolete top-level version: field. Docker's Compose file reference names compose.yaml as the preferred filename and retains docker-compose.yml for compatibility. Use the current docker compose command.

docker compose config --quiet validates and resolves configuration without starting a container; it doesn't prove the scorer works or that its mount is readable. docker compose run --build --rm scorer first builds the service image, then creates a one-off container. --build matters after a source edit because an existing tag may still point at an older image. --rm removes the container after the scorer exits, while the image remains available.

As the RAG stack gains real services, add their images, commands, and mounts to this same file. Until then, keep the scorer as the only service so another engineer can run the file as written.

Keep credentials out of image layers

The scorer doesn't need an API key yet, so don't give it one. Least privilege starts by attaching no secret to a process that doesn't use it. When a future build needs private-package access, separate that short build lifetime from the runtime secret a process reads later.

When a build must authenticate to a private package index, don't pass the credential with ARG or ENV. ARG isn't copied into the running container the way ENV is, but it still isn't safe. The Dockerfile reference warns that build-arg values appear in docker history and max-mode provenance attestations.

This bad pattern puts the token in a build argument. Don't run it with a real credential:

# BAD: ARG values can appear in image history and provenance attestations
ARG PRIVATE_INDEX_TOKEN
RUN python -m pip install --index-url "https://token:${PRIVATE_INDEX_TOKEN}@packages.example.invalid/simple" private-package

BuildKit, Docker's build engine, has a separate secret-mount channel. The mounted file is available only for that RUN instruction and isn't committed to its layer. Commands can still leak it by copying its contents elsewhere or printing them, so the channel doesn't replace careful handling.^{[11]Reference 11Build secretshttps://docs.docker.com/build/building/secrets/}

If requirements.txt later needs a private index, replace its install instruction in the builder stage with this fragment. required=true fails clearly when the build command forgets to supply the secret:

RUN --mount=type=secret,id=pip_config,target=/etc/pip.conf,required=true \
    python -m pip install --require-hashes -r /tmp/requirements.txt

Supply that temporary file from the build command:

docker build \
  --secret id=pip_config,src="$HOME/.config/pip/pip.conf" \
  -t access-rag:private .

Runtime secrets use a separate channel. Docker's Compose guidance warns against putting passwords or API keys in environment variables, because container configuration and diagnostic tooling can expose them. When the scorer later calls an API, mount a Compose secret as /run/secrets/access_api_key or use the deployment platform's secret manager, then have the process read that file. Keep env_file for non-sensitive settings such as log level or feature mode.^{[12]Reference 12Manage secrets securely in Docker Composehttps://docs.docker.com/compose/how-tos/use-secrets/}

Once the scorer reads that file, extend the existing Compose model with this fragment:

services:
  scorer:
    secrets:
      - access_api_key

secrets:
  access_api_key:
    file: ./secrets/access_api_key.txt

Don't add this fragment before the process consumes the file. Local Compose mounts a host file; it doesn't encrypt that file or remove host-access risks. Keep it out of Git, restrict its host permissions, and verify that appuser can read the mounted secret without granting unrelated users access.

Keep secrets/ and .env* in both .gitignore and .dockerignore. Those exclusions protect two different routes out of your machine. Explicit build-secret and runtime-secret mounts deliver the selected file without copying it into ordinary image layers.

When the GPU enters the story

The CPU-first image is the right base here. It works through Docker Engine or Docker Desktop on common Linux, macOS, and Windows development machines. For the Linux Docker Engine path below, a CUDA workload needs a compatible NVIDIA GPU, an installed host driver, and NVIDIA Container Toolkit configuration that exposes selected devices to the container. CUDA user-space libraries live in the application image; the kernel driver stays on the host.^{[13]Reference 13NVIDIA Container Toolkit Installation Guidehttps://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html}

Windows also has a supported GPU path: Docker Desktop with its WSL2 backend and a compatible NVIDIA Windows driver can expose the GPU to Linux containers. Use Docker's Windows-specific setup and validation instructions for that path; the systemctl and Linux driver commands below configure a Linux Engine host.^{[14]Reference 14GPU Support in Docker Desktop for Windowshttps://docs.docker.com/desktop/features/gpu/}

When the same scorer later becomes a GPU workload, don't start by swapping Python packages. First ask which boundary can see the device: the host, the container runtime, or the framework inside the image.

After installing the toolkit on a systemd-managed Docker Engine host, configure its runtime and restart the daemon:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Rootless Docker uses a user-scoped daemon configuration and restart command, so follow NVIDIA's rootless instructions instead of copying the system-wide commands.

When a later PyTorch or inference chapter needs GPU acceleration, keep the same habits and change only the platform-specific pieces:

Don't promise that one CUDA image gives Apple Silicon and NVIDIA parity. Docker Desktop on Apple Silicon can run this Linux CPU image, but it doesn't turn the Mac GPU into an NVIDIA CUDA device. Use the later Metal/MPS path for native Mac PyTorch, and test production CUDA images on compatible Linux NVIDIA hosts.

Before running the smoke test, predict what it can prove: device exposure through Docker, not that a particular PyTorch build is compatible. NVIDIA uses a plain ubuntu image so the toolkit can expose nvidia-smi without coupling the check to a CUDA application image.^{[15]Reference 15Running a Sample Workload with Dockerhttps://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/sample-workload.html}

sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

Read GPU failures in layers:

The smoke test checks device exposure. It doesn't establish compatibility with a chosen PyTorch image. Read the table from top to bottom: fix the host first, then the container runtime, then the application image. For a real workload, select an official framework or CUDA image whose architecture and CUDA runtime match the locked Python packages. Verify its documented minimum driver requirement, then pin that application image for the release as you pinned the CPU base.

A build-and-run gate

The separate checks can become a small Bash script for local use or continuous integration (CI), the automated checks run after a code change. Run both fixture paths: a passing mounted run can hide a missing or broken baked fixture. Save this as scripts/check_container.sh and run it from the project root with bash scripts/check_container.sh:

#!/usr/bin/env bash
set -euo pipefail

docker build --check .
docker build -t access-rag:check .
image_id=$(docker image inspect --format '{{.Id}}' access-rag:check)
expected_report=$(cat <<'EOF'
Eval rows: 3
Exact-match accuracy on tiny fixture: 0.667 (2/3)
Gate passed. You may commit.
EOF
)
baked_report=$(docker run --rm --read-only "$image_id")
mounted_report=$(docker run --rm \
  --read-only \
  --mount type=bind,source="$PWD/eval",target=/app/eval,readonly \
  "$image_id")
if [[ "$baked_report" != "$expected_report" ]]; then
  printf '%s\n' "ERROR: baked fixture report changed" "$baked_report" >&2
  exit 1
fi
if [[ "$mounted_report" != "$expected_report" ]]; then
  printf '%s\n' "ERROR: mounted fixture report changed" "$mounted_report" >&2
  exit 1
fi
printf '%s\n' "$baked_report" "Verified local image: $image_id"
if docker compose version >/dev/null 2>&1; then
  docker compose config --quiet
else
  echo "Docker Compose plugin missing. Install docker-compose-plugin before enabling the compose gate."
fi

set -euo pipefail stops this script when a mandatory command fails. A missing Compose plugin is deliberately reported and skipped; an installed plugin with invalid configuration fails the script. On an older Docker release without docker build --check, upgrade or temporarily omit only that static check. Neither static check substitutes for running the image.

The scorer's exit status enforces its existing threshold, at least two-thirds correct. It doesn't require exactly 0.667: three matches would pass too. The two report comparisons separately enforce this unchanged starter fixture's exact result. Deliberately updating the fixture requires reviewing that expected report too. A threshold check and an exact regression check answer different questions.

For a small regression exercise, change request 102's host prediction to blocked, then rerun the script. Predict the two reports first. The script rebuilds the image, so both runs report 3/3, which passes the scorer's threshold. The exact comparison nevertheless exits with ERROR: baked fixture report changed. Restore the committed row before continuing. This failure distinguishes changed input from a broken container runtime.

Both runs use the captured local image ID, so reassigning access-rag:check between commands won't switch the artifact under test. A local identity doesn't prove the image exists in a deployment registry. Before deployment, record and promote the registry's verified repository@sha256:... reference for the tested image. Don't construct that reference by attaching a local ID to a registry URL. Docker distinguishes image IDs from repository digests, and its push or pull output reports the registry digest.^{[16]Reference 16docker image ls: image IDs and digestshttps://docs.docker.com/reference/cli/docker/image/ls/}

Failures you'll see first

Document the diagnosis, command, and prevention in the repo so the next clone can reproduce the fix without rediscovering it.

What survives a fresh clone

Commit the Dockerfile, .dockerignore, requirements.txt, compose.yaml, and scripts/check_container.sh alongside the scorer and fixture. Repeat the previous lesson's temporary-clone check after committing these files, then run bash scripts/check_container.sh inside that clone. The builder should see only committed project inputs. Another engineer should be able to run both fixture paths and reproduce the empty-mount failure without borrowing your virtual environment or credentials.

Before publishing a release image, pin the base digest and deployment platform, lock any dependencies, and record the image identity with the successful run output. These controls constrain the inputs; they don't guarantee bit-for-bit identical rebuilds or identical GPU numerical results. For deployment, promoting one tested image by digest is a stronger guarantee than rebuilding the same recipe on every machine.

Separate the files that belong in the image from the files that arrive on a mount, and expect a known failure when the eval directory is missing. The scorer is still a command that prints 0.667. Follow that command through one row: how it parses a field, compares a label, and decides the gate.