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, not the image it came from. Another run can reuse the image. 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 doesn't share the macOS 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.

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:

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:

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. Wrap those same files; don't write a second implementation just to please Docker. One scorer gives the container a result we can compare with the Git check.

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:

That output is the baseline the image must preserve. The next step gives it a runtime without changing the scorer or fixture.

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:

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.

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/}

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:

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

Expected output:

Inspect the artifact as well as its stdout:

The platform should match the build target, the configured user should be appuser, and the entrypoint should name the scorer. --read-only proves this workload doesn't need to mutate its container filesystem. PYTHONDONTWRITEBYTECODE=1 keeps Python from trying to write .pyc files when that filesystem is locked.

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:

A bind mount obscures the copied eval

A green run proves the image can read its baked fixture. But 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:

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.^{[8]Reference 8Volumeshttps://docs.docker.com/engine/storage/volumes/}

Turn one boundary into a failure

Test the mount behavior without renaming or deleting the committed fixture. Create an empty scratch directory and mount it over /app/eval:

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:

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:

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.^{[9]Reference 9Compose service referencehttps://docs.docker.com/reference/compose-file/services/}

Validate the file before running it:

Docker Desktop includes Compose. Some Linux Engine installs need the docker-compose-plugin package first.^{[10]Reference 10Docker Documentation.https://docs.docker.com/} If docker compose version is unknown, the Dockerfile still works through docker run, but the Compose workflow isn't installed yet. The old top-level version: field is obsolete, so omit it. compose.yaml is the preferred filename. docker-compose.yml remains a backward-compatible name. Use the hyphen-free docker compose command; Docker documents the standalone docker-compose install only for compatibility.

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.

When the RAG stack grows, add vector-db, api, and worker services to this same file. Don't add fake services before they exist. A Compose file that starts today beats an impressive YAML file that fails on the first command.

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. Docker's docs warn that build-arg values show up in docker history and in max-mode provenance attestations:

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

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:

Supply that temporary file from the build command:

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:

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:

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:

Read GPU failures in layers:

The smoke test proves device exposure, not that a chosen PyTorch image is compatible. 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, and 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.

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. For the unchanged starter fixture, compare stdout with the expected 0.667 (2/3) as well. A threshold check and an exact regression check answer different questions.

Failures you'll see first

The useful habit isn't memorizing each Docker flag. Put the diagnosis, the command, and the prevention in the repo so the next clone doesn't have to rediscover them.

What survives a fresh clone

Commit the Dockerfile, .dockerignore, requirements.txt, and compose.yaml alongside the scorer and fixture. Another engineer should be able to build, 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.

The container now makes the runtime assumptions visible. Python is the remaining part we've treated as a command to execute rather than code to understand. Opening the scorer next will connect that command to the row parsing, comparisons, and error handling behind its output.