Module 02: Dockerfiles
Build, Layers & the Cache

Module 01 ended on a cliff: "data you write inside a container is not in the image, and a package you install with docker exec vanishes on docker rm." Sam hit this wall hard. Every time their app's container restarted, the dependencies Sam had hand-installed were gone. The fix to that, the only proper one, is to bake what you need into the image at build time. That is what a Dockerfile does, and it's exactly the tool Sam needs to ship for real.

A Dockerfile is a text file (literally named Dockerfile, no extension) listing the steps to assemble an image, top to bottom. docker build reads it, runs each instruction in order, and snapshots the filesystem after each one into a layer. The final stack of layers is your image.

Here is the smallest useful, real-world example, the Python web app Sam is shipping. Read it once; we dissect every line below.

# 1. Start from an official base image (pinned tag)
FROM python:3.12-slim

# 2. Set the working directory inside the image
WORKDIR /app

# 3. Copy ONLY the dependency manifest first (cache trick: section 4)
COPY requirements.txt .

# 4. Install dependencies
RUN pip install --no-cache-dir -r requirements.txt

# 5. Now copy the rest of the source code
COPY . .

# 6. Document the port the app listens on
EXPOSE 8000

# 7. The default command when a container starts
CMD ["python", "app.py"]

Build it and run it:

# -t names (tags) the image; the "." is the build context (section 5)
docker build -t myapp:1.0 .

# run a container from the image you just built
docker run -p 8000:8000 myapp:1.0

There are ~18 Dockerfile instructions. You use about 10 daily. Know these by heart, because you'll use the distinctions constantly (especially the ones marked).

ADD vs COPY (common gotcha)

Both copy files in. ADD has two extra "magic" behaviours: it auto-extracts a local .tar and can download a remote URL. That magic causes surprises and security issues, so the rule the docs themselves give: use COPY always, reach for ADD only when you specifically want tar auto-extraction. Knowing this signals you've read the guidelines.

This pair confuses everyone at first and is asked constantly. Sam tripped here too: their app ignored docker stop until they understood the split. The clean way to hold it:

They combine. With both set, the container runs ENTRYPOINT + CMD. Anything you type after the image name on docker run replaces the CMD part:

ENTRYPOINT ["ping"]
CMD ["localhost"]

# docker run myimg            -> ping localhost   (uses default CMD)
# docker run myimg google.com -> ping google.com  (CMD replaced by arg)

This is the most valuable thing in the module, and the part that finally made Sam's builds bearable. Sam's rebuild was crawling at 12 minutes per code change, killing their shipping momentum. The cache is the fix. docker build caches each instruction's result. On the next build it walks down the Dockerfile and, for each instruction, asks: "has this instruction or any instruction above it changed?"

• No change → reuse the cached layer instantly (you'll see CACHED in the output).
• Changed → rebuild this layer and every layer below it. The cache is invalidated downward.

That second rule, a cache miss cascades to everything underneath, is the whole game. It means instruction order decides rebuild speed. Put the things that rarely change near the top, the things that change constantly (your source code) near the bottom.

The classic mistake vs the fix

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
CMD ["python", "app.py"]

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

In the left version, editing one line of source changes the COPY . . layer, which sits above the pip install, so dependencies reinstall on every build (minutes). In the right version, requirements.txt rarely changes, so its layer and the pip install stay cached; only the final COPY . . reruns (seconds).

What the cache actually does on a code-only edit, layer by layer:

The . at the end of docker build -t myapp . is the build context: the directory the daemon receives to build from. COPY can only see files inside it. Crucially, the entire context is sent to the daemon first, so if your folder has a 500 MB node_modules, a .git history, and your virtualenv, all of it ships before the build even starts. Slow builds, fat images, leaked secrets.

Fix: a .dockerignore file (same syntax as .gitignore) next to the Dockerfile. It excludes paths from the context entirely.

.git
node_modules
__pycache__
*.pyc
.env
.venv
Dockerfile
README.md

Building an app often needs heavy tooling (compilers, build deps, dev packages) that the final running image does not need. Shipping all of it makes a 1 GB image where 80 MB would do. Multi-stage builds solve this: use multiple FROM stages, do the heavy work in an early "builder" stage, then copy only the finished artifact into a clean, tiny final stage. Everything in the builder stage is thrown away.

# ── stage 1: build (heavy toolchain) ──
FROM golang:1.22 AS builder
WORKDIR /src
COPY . .
RUN go build -o /bin/app ./cmd/app

# ── stage 2: final (tiny, runtime only) ──
FROM gcr.io/distroless/base-debian12
COPY --from=builder /bin/app /app
ENTRYPOINT ["/app"]

The magic line is COPY --from=builder /bin/app /app: it pulls just the compiled binary out of the builder stage. The Go compiler, source code, and module cache never reach the final image. A 900 MB builder collapses into a ~20 MB final image.

The habits that separate a professional Dockerfile from a tutorial one. Each is a habit worth building.

RUN apt-get update \
 && apt-get install -y --no-install-recommends curl \
 && rm -rf /var/lib/apt/lists/*

# create an unprivileged user and switch to it
RUN useradd --create-home appuser
USER appuser

Reading this module teaches you nothing until you watch the cache hit and miss yourself. This is the exact loop that turned Sam's 12-minute rebuild into seconds. Spend 30 minutes here.

• Make a folder with a trivial app (a requirements.txt with one package + a 3-line app.py). Write the "slow" Dockerfile from section 4.
• Build it twice in a row. Watch the second build: every line says CACHED. Time it.
• Change one line in app.py and rebuild. Notice pip install reruns even though deps didn't change. That's the bug.
• Switch to the "fast" Dockerfile (copy requirements first). Rebuild, edit app.py, rebuild again. Now pip install stays CACHED. Feel the difference.
• Run docker history myapp:1.0 and docker images to see each layer's size and the total image size.
• Add a .dockerignore, then add a fake .env to the folder. Confirm with docker build output that the context shrank.
• Convert any compiled-language toy (or a Node app) to a multi-stage build. Compare image sizes before/after with docker images.
• Break the cache on purpose: docker build --no-cache and watch every layer rebuild.

You asked the right question. Here is the honest map. You are 3 of ~8 Docker modules in. The good news: you can start a real project sooner than you can claim full mastery. Those are two different milestones. Sam is shipping already, hardening comes later.