Lesson 02 — Dockerfile Design

Multi-stage builds, image-size optimization, and Python-specific patterns.

Cloud & DevOps Module 1

Why image size matters

What’s in the 180 MB image

• ~120 MB slim Debian base
• ~60 MB Python deps (wheels you installed)
• Of the 60 MB, ~30 MB is build-time only: gcc, libffi-dev, headers needed to compile wheels
• The runtime container doesn’t need any of that

The big idea: multi-stage builds

• Each FROM in a Dockerfile starts a new stage with its own filesystem
• Only the final stage’s layers end up in the published image
• Earlier stages can be referenced by name and files copied out
• The heavy stage is discarded — it never ships to your registry

Multi-stage Dockerfile — minimal example

# Stage 1: build
FROM python:3.11-slim AS builder
WORKDIR /build
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

# Stage 2: runtime
FROM python:3.11-slim
COPY --from=builder /install /usr/local
WORKDIR /app
COPY app.py .
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

• AS builder — names the stage so the next FROM can reference it
• --prefix=/install — keeps installed packages in a controlled location
• COPY --from=builder — the magic: brings only the artefacts forward

pip install --prefix vs virtualenv vs --target

Cache mounts (BuildKit)

# syntax=docker/dockerfile:1.7
FROM python:3.11-slim AS builder
WORKDIR /build
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install --prefix=/install -r requirements.txt

• The cache mount persists between builds without becoming part of the image
• Massive win on dep-heavy projects: first build ~30 s, subsequent builds ~3 s
• Published image still doesn’t carry the pip cache — it’s mounted, not copied
• DOCKER_BUILDKIT=1 (default in Docker Desktop 23+) enables the syntax

Going further: uv

FROM python:3.11-slim AS builder
RUN pip install --no-cache-dir uv
WORKDIR /build
COPY requirements.txt .
RUN uv pip install --system --prefix=/install -r requirements.txt

• uv is Astral’s Rust-based pip replacement
• 10–50× faster than pip for resolve+install
• Uses the same wheel format — drop-in replacement
• --system skips uv’s automatic venv creation when using a prefix

What’s in python:3.11-slim — and why “slim” still isn’t slim

• Full glibc (~20 MB)
• apt, dpkg, package manifest database (~30 MB)
• A shell (/bin/sh, /bin/bash)
• /etc/passwd machinery, locale data, certificates
• ~120 MB of “things that aren’t your app”

Distroless: the next size tier

FROM python:3.11-slim AS builder
# ... build into /install ...

FROM gcr.io/distroless/python3-debian12
COPY --from=builder /install /usr/local
WORKDIR /app
COPY app.py .
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

• ~30 MB runtime image
• No shell, no package manager, no apt
• Trade-off: can’t docker exec ... /bin/sh — use docker exec ... python -c "..." instead
• CVE surface drops dramatically — most CVEs are in the OS utilities you don’t need

.dockerignore is mandatory

__pycache__/
*.pyc
.venv/
.git/
.pytest_cache/
*.md
tests/

• Keeps the build context small — du -sh before and after: often a 10× reduction
• Security: without it, .git/ history (and possibly .env secrets) get streamed to the daemon
• A stray .env can end up baked into an intermediate cache layer

Layer ordering revisited

Pinning and reproducibility

• Pin the Python version — python:3.11.9-slim, not python:3.11-slim
• Pin every wheel — pip-compile / uv pip compile produces a fully-pinned lockfile
• Pin the base by digest in production — python@sha256:...
• Tag drift between latest and “what you built last week” is a leading cause of “it worked yesterday”

What lands in sample-app/ after this lesson

Recap & what’s next

• Multi-stage = build heavy, ship light; discard compilers and headers at the boundary
• Cache mounts save dep-install time without polluting the published image
• Pinning everything (version, deps, base digest) is non-negotiable for reproducibility