One image.
Every machine.

An AI stack is not one program. It is Python, PyTorch, CUDA drivers, cuDNN, system-level C libraries, and packages like flash-attn that were compiled against an exact combination of the others. Each layer has its own version number, and the combinations that work are a small island in a large sea. When the three machines disagree, there is nothing to debug: the environment itself is the bug.

A container wraps the code, the runtime, the libraries and the system tools into one isolated unit that runs identically everywhere. It is not a virtual machine. A virtual machine boots a whole guest operating system with its own kernel; a container shares the host kernel and isolates at the process level, so it starts in seconds instead of minutes. That one design choice is why a 9 GB image can feel instant — and why containers, not virtual machines, became the unit of AI software.

The source’s framing is worth keeping: Docker is a lightweight virtual machine that shares the host OS kernel instead of running its own. The kernel is the part every container on a machine has in common, so it cannot be part of the image — and that is precisely why the GPU driver also stays outside. A container carries the CUDA toolkit; the host supplies the driver that talks to the physical card. Chapter 03 and chapter 04 come back to that split, because it is the single most confusing thing about GPUs in Docker.

An image is a read-only template — the recipe card. A container is a running instance of that image — the kitchen built from the card today. The Dockerfile is the recipe itself, written as instructions that Docker executes layer by layer. A volume is storage that survives the container: the pantry, outside the kitchen. And Docker Compose (compose is short for composition, the act of putting parts together) is the manager who opens several kitchens at once from a single YAML (YAML Ain’t Markup Language) file.

The word layer is the one that pays rent. Each Dockerfile instruction produces one layer — a filesystem snapshot that Docker stores by content and reuses whenever the instruction and its parent are unchanged. The source’s Dockerfile has seven: the FROM base (≈4 GB of CUDA toolkit and compilers), an apt layer that installs Python 3.12 and erases the package lists, a hash-verified get-pip layer, a pip upgrade, the pinned PyTorch wheels (≈2.5 GB), the AI library set (≈1.3 GB), and a metadata layer that records the working directory, the mount points, the port and the default command. Change an early layer and every layer after it is rebuilt; leave it alone and the whole stack comes back from cache in seconds. That is why AI images are practical at all: the 4 GB base is downloaded once, and a rebuild after a code edit usually costs nothing.

One: GPU (graphics processing unit) drivers are fragile. CUDA 12.4 code does not run on CUDA 11.8 — the versions are not interchangeable, and a PyTorch wheel is compiled against exactly one of them. The source’s resolution splits the problem in two: the CUDA toolkit (≈4 GB of libraries and compilers) lives inside the container, while the GPU driver stays on the host and is shared through the NVIDIA Container Toolkit. One driver, many toolkits — which is why the same ai-dev image can run on a workstation, a training node and a laptop with a different Python entirely.

Two: model weights are large. A 7-billion-parameter model is 14 GB in fp16 (16-bit floating point) — 2 bytes per parameter. A rebuild should never re-download it, because 14 GB is 14 × 1024 = 14,336 MB, which is ≈ 2 min 23 s on a 100 MB/s link and ≈ 12 min on a 20 MB/s one, times every rebuild and every teammate. The fix is a volume: -v ~/models:/models keeps the weights on the host, and the container reads them from a path that never changes.

Three: real AI applications are multi-service. A retrieval-augmented generation (RAG) application is not a script: it is an inference server, a vector database for retrieval, and often a web frontend. Running each one by hand means three terminals, three networks and three sets of flags. Docker Compose describes all of them in one YAML file and starts them with one command, on a shared network where they address each other by name.

The honest arithmetic behind reason two. One 7B model in fp16 is 14 GB, and a single rebuild without a volume would pull all 14 GB again. Instead of trusting that intuition, price it: on the lesson’s 100 MB/s teaching link the download is ≈ 2 min 23 s; three teammates × two rebuilds is six downloads, ≈ 14 minutes of pure network and 86 GB of transfer. Mount ~/models once and the number is zero — for every rebuild, every container and every teammate who pulls the image. The image never contains the weights, which is also why the image stays around 9 GB instead of 23 GB.

Docker has two pieces: a daemon (dockerd) that does the real work, and a client (the docker command) that talks to it. Docker Desktop packages both for macOS and Windows; on Linux they come from Docker’s own repository. The commands below are the source’s, verbatim.

Step 2 is only for Linux machines with an NVIDIA GPU. The NVIDIA Container Toolkit installs a runtime hook that teaches Docker how to hand the host GPU to a container. macOS and Windows (WSL2) users skip it: Docker Desktop handles GPU passthrough differently on those platforms. The source gives the exact keyring and apt dance, because the toolkit is not in the default Ubuntu repositories.

Then the test that decides everything. It runs a small CUDA image, asks the container to run nvidia-smi — the NVIDIA System Management Interface — and the answer comes from the physical card on the other side of the runtime hook:

No GPU? The fallback is a first-class path. Remove --gpus all from the run command and the NVIDIA deploy block from the compose file (chapter 07), and everything still works for CPU lessons: PyTorch detects the absence of CUDA and runs on the CPU automatically. The images are identical, the flags are not — which is exactly the kind of difference a Dockerfile is supposed to make forgettable.

First, choose the starting point. The FROM image decides what you do not have to install — and what you can never remove. The source lays out four options and when each is right:

Now the file itself. This is code/Dockerfile from the source, unedited:

The walkthrough, instruction by instruction. Read it as a shopping list with a budget; the numbers in the sidebar are teaching estimates, but the reasons are not:

Build it. The trailing dot is not decoration: it is the build context, the directory Docker is allowed to read from. The source’s command runs from the repository root because the file lives deeper in the tree:

The ordering lesson, with numbers. The source’s development image never copies code — it mounts it — so a code edit is not a rebuild at all. Production images do copy code, and then the order of the file becomes a cost decision with a 34× range. Put COPY . /workspace above the pip layer and editing one line of app.py invalidates the 260-second pip install plus everything after it: ≈ 269 s. Put the COPY requirements.txt + pip install -r pair first and the code copy last, and the same edit rebuilds ≈ 2 s of copying plus 5 s of compilation — ≈ 8 s. Same application, same dependencies, same cache rule; only the order changed.

The source is blunt about why this matters: without volume mounts, your 14 GB model downloads vanish when the container stops. The mechanics are simple. Each container gets a writable layer; when the container is removed — and --rm removes it the moment the command exits — that layer goes with it. The image underneath is untouched, the volumes attached to it are untouched, and everything written to a plain container path is gone.

A bind mount maps a directory you can see in your own file manager into the container: -v ~/models:/models is host path first, container path second. A named volume is storage Docker manages for you, referenced by name — the compose file in chapter 07 uses one for the vector database. Both outlive containers; the difference is who owns the directory.

The arithmetic that justifies the habit. A 7-billion-parameter model is 14 GB in fp16. On the lesson’s 100 MB/s example link, re-downloading it is 14 × 1024 ÷ 100 ≈ 143 s — call it 2 min 23 s, every time, per machine. Drop to a 20 MB/s connection and it is ≈ 12 min. Multiply by a week of rebuilds and the volume mount is not a nice-to-have; it is the difference between an afternoon of work and an afternoon of waiting. And it is not only models: checkpoints larger than the base model, embedding indexes, and multi-gigabyte datasets all have the same property — large, stable, and expensive to fetch.

One more nicety from the source’s VOLUME line: it makes the contract explicit. A reader of the Dockerfile can see which paths are meant to be mounted, and Docker can warn when a run has no volume where one was expected. It is documentation with teeth — the same instinct as EXPOSE, one chapter earlier.

A real AI application is not a Python script: it is a service that answers questions, a vector database that supplies context, and usually a frontend. Docker Compose describes that arrangement once, in YAML, and runs it with one command. The source’s file has exactly two services: ai-dev, which builds the Dockerfile from chapter 05 and keeps the GPU reservation, the three volume mounts and port 8888; and qdrant, the vector database image, with ports 6333 (REST, the HTTP/JSON API) and 6334 (gRPC, a binary remote-procedure-call protocol) and a named volume for its storage.

The part Compose adds that no flag does: a network. Compose creates a network for the project and runs a DNS (Domain Name System) resolver at 127.0.0.11 inside it. Every service gets its name as a hostname, so from inside the AI container http://qdrant:6333 just resolves. The source’s test is the proof:

The commands worth knowing by heart. The source ends its build steps with a short list; each one answers a question you will ask this month: