Images, layers & optimization

This tiny Python program models the Docker build cache so you can see, in plain numbers, why instruction order matters. It is not running Docker — it is simulating how long a rebuild takes given which layer you changed.

1. rebuild_time(layers, changed) takes a list of layers — each is a (name, seconds) pair saying how long that step takes — and a set of layer names that changed since last build.
2. It walks the layers in order. The moment it hits a changed layer it flips broken = True, meaning "the cache is broken from here on". Every layer from that point adds its secs to total; layers before the change stay cached and cost nothing.
3. good installs dependencies before copying code; bad copies code before installing. Both then simulate the same everyday action: you edited COPY code.
4. In good order, COPY code is last, so only its 1 second rebuilds. In bad order, changing the earlier COPY code layer forces the 40-second RUN pip install that sits after it to run again.

What the output means: GOOD order: 1 s vs BAD order: 41 s — the exact same code edit is 40× slower to rebuild purely because the dependency install was placed after the code copy.

Try this: Change {"COPY code"} to {"FROM"} and re-run: changing the very first layer rebuilds everything, so both orders become slow. That is why the base image goes first — you almost never change it.

This is the same lesson as the Python model, but written as a real Dockerfile. Each line is one instruction that becomes one layer, and the ordering is deliberately chosen so the slow step stays cached.

1. FROM python:3.12-slim picks the starting image (a small Python). WORKDIR /app sets the folder inside the image where the next commands run.
2. COPY requirements.txt . copies only the dependency list first — on its own, before your code. Your requirements change rarely, so this layer (and the install after it) usually stays cached.
3. RUN pip install ... -r requirements.txt is the slow step. Because it sits right after the requirements copy, Docker re-uses its cached result on every build where requirements.txt did not change.
4. COPY . . copies your actual source code last, because it changes on almost every build. Only this final layer rebuilds when you edit your code — the expensive install above stays cached.

Try this: If you instead put COPY . . above the pip install line, every code edit would re-run the install. This one ordering choice is the single most common Docker speed-up.

Before Docker builds anything, it bundles up your project folder and sends it to the builder — this bundle is called the build context. A .dockerignore file lists what to leave out of that bundle, exactly like .gitignore keeps files out of Git.

1. Each line is a file or folder pattern to exclude. .venv/, __pycache__/ and *.pyc are local Python junk that has no business inside the image.
2. .git/ (your whole version history) and tests/ are large and not needed to run the app, so excluding them shrinks the context and the image.
3. .env and *.md matter for a different reason: .env holds secrets you must never copy into an image, and docs just add weight.
4. The final comment states the two payoffs: a smaller context builds faster, and nothing secret or bulky can accidentally get copied in by a broad COPY . ..

Try this: Add a giant file like data/ to a project with no .dockerignore and watch docker build pause on "sending build context" — that pause is Docker uploading everything you forgot to ignore.

A multi-stage build uses two images in one Dockerfile: a big "builder" that has all the compilers and dev tools needed to install things, and a tiny "runtime" that ships to production with only the finished result — no build tools.

1. FROM python:3.12 AS builder starts the first stage on the full Python image (includes compilers). Naming it AS builder lets a later stage copy files out of it.
2. RUN pip install --target=/deps ... installs all dependencies into one folder (/deps) inside the builder, so the whole result is easy to grab in one move.
3. FROM python:3.12-slim begins the second stage on the small image. This is a fresh start — none of the builder's compilers come along automatically.
4. COPY --from=builder /deps ... reaches back into the builder stage and copies only the installed packages into the slim image. COPY . . adds your code, USER 1000 switches off the root account, and only this slim stage is what actually ships.

Try this: The pairing with the next lab is the point: the fat builder can be 400 MB of tools, but because none of it is copied forward, the final image only carries the base + dependencies + your code.

This program puts a number on the multi-stage saving. It adds up the megabytes an image carries and shows how much you cut by leaving build tools behind.

1. image_size(base_mb, deps_mb, build_tools_mb, multistage) sums the pieces of an image: the base OS, your dependencies, and (only for a single-stage build) the heavy build tools.
2. The key line adds build_tools_mb only when multistage is False: (0 if multistage else build_tools_mb). A multi-stage image carries zero build-tool weight.
3. single and multi call it with identical numbers (150 MB base, 120 MB deps, 400 MB tools) — the only difference is the multistage flag.
4. The f-string prints each total, and round(100*(single-multi)/single) computes the percentage shrink so the win is stated as a headline figure.

What the output means: single-stage: 670 MB vs multi-stage: 270 MB (60% smaller) — dropping the 400 MB of build tools cuts the shippable image well over half.

Try this: Bump build_tools_mb from 400 to 800 and re-run — the multi-stage image stays 270 MB while the single-stage balloons, so the percentage saving climbs even higher.

These shell commands are the detective tools for a bloated image: they show you which layer added the weight, and how to force a clean rebuild. Run them in a terminal where Docker is installed.

1. docker history myapp --human lists every layer of the image myapp with the size each one added, in human-readable units (MB/GB). This is how you spot the one instruction that added 400 MB.
2. docker image inspect myapp --format '{{.Size}}' prints just the total image size as a single number — handy for scripts and before/after comparisons.
3. docker build --no-cache -t myapp . rebuilds from scratch, ignoring every cached layer. Use it to prove a fresh build works or to bust a stale cache.
4. The comment flags a classic trap: if a RUN downloads a big file and a separate later RUN deletes it, the bytes are already committed in the earlier layer forever. Chain download-use-delete in one RUN ... && ... so they never land in a layer.

Try this: On any image you have locally, run docker history <image> --human and read it top-to-bottom: the fattest lines are your optimisation targets.

This is the production-ready Dockerfile — it folds in every safety practice from the lesson: small base, cache-friendly order, a non-root user, and a health check so the platform knows the app is alive.

1. The first four lines are the cache-friendly pattern you already saw: slim base, WORKDIR, copy requirements.txt first, then pip install.
2. RUN useradd --create-home appuser creates an ordinary user, then USER appuser switches to it. Everything after runs as this user, not root — so a break-in has far less power. COPY --chown=appuser . . gives that user ownership of the code.
3. HEALTHCHECK tells Docker how to test if the app is healthy: every 30s it runs a tiny Python one-liner that fetches /healthz. If that fails, the container is marked unhealthy and can be restarted.
4. CMD ["uvicorn", ...] is the command that actually launches the web app when the container starts, binding it to all interfaces on port 8000.

Try this: Compare this with Dockerfile.cache above: the differences (non-root user, --chown, HEALTHCHECK) are exactly the boxes the scorer in the next lab checks for.

This turns the hardening checklist into an automatic grade. Instead of arguing about whether an image is "good enough", a CI pipeline runs this scorer and blocks anything that scores too low — policy, not opinion.

1. score_image(facts) starts every image at a perfect 100 with an empty notes list, then subtracts points for each problem it finds.
2. The penalties are weighted by how much each issue matters: too big (-25), runs as root (-40), and has_secrets is a fatal -100 — one baked-in secret alone drops the score to zero. Every deduction also appends a human-readable reason to notes.
3. max(score, 0) stops the score going negative, and the function returns the number plus the list of reasons so a human can see why it failed.
4. good and bad are two example fact sheets. The final line applies the gate: PASS if the score is >= 70, otherwise FAIL.

What the output means: good: (100, []) passes clean; bad hits every penalty, lands at 0 with all five reasons listed, and the gate prints PASS / FAIL.

Try this: Flip one field of bad — say set has_secrets=False — and re-run. The score jumps by 100 but other penalties may still keep it under 70, showing how a single fix is rarely enough to pass the gate.