ProjekinAja. Software Engineering Stage 5 · Shipping & Running Lesson 5.2
● Stage 5 · Lesson 5.2

Containers: What Docker Actually Is

Namespaces, cgroups, and layered filesystems — three Linux features in a trench coat, not a VM and not magic.

⏱ ~18 min read 🐋 Container mechanics 🔧 TraceLab v4 milestone

🎯 By the end you'll understand

What Docker actually is at the kernel level — process isolation via namespaces, resource limits via cgroups, and images as stacked immutable layers. You'll understand why COPY ordering determines build cache hit rate, what a 1.2 GB image means architecturally, why containers are not a security boundary, and how to write TraceLab's production Dockerfile with multi-stage discipline that takes the image from 1.2 GB to ~150 MB.

KEY INSIGHTA container is a process with a restricted view of the world

Docker did not invent containers. It wrapped Linux kernel features that existed since 2002 (namespaces) and 2008 (cgroups) into a usable CLI and a distribution format. The magic is the packaging, not the isolation.

Before Docker, deploying software meant hoping the server had the right Python version, the right shared libraries, and a compatible glibc. Docker's insight was not a new isolation primitive — it was a reproducible artifact format plus a simple CLI. Understanding what's underneath lets you debug the failure modes that the abstraction papers over.

🔑 Hold onto this

A running container is an ordinary Linux process. The kernel has arranged for that process to see a restricted namespace (its own PID tree, network interface, filesystem root) and enforced resource limits via cgroups. If you docker exec -it mycontainer bash, you get a shell. That shell is a child process of the container entrypoint — it uses the same kernel as every other process on the host. There is no hardware boundary, no separate boot, no hypervisor. A container is a process with walls painted around it, not a cage made of steel.

HOW IT WORKSThree Linux primitives in a trench coat

Docker's isolation rests on three kernel features. You don't need to operate them directly, but you need to know what each one does and what it does not do.

1

Namespaces — what the process can see

A namespace wraps a global kernel resource so the processes inside see their own private copy. Linux has eight namespace types; Docker uses six of them. The two that matter most day-to-day:

  • PID namespace — the container's init process (your CMD) gets PID 1 inside the namespace; it cannot see host PIDs. This is why killing the PID-1 process kills the container.
  • Network namespace — the container gets its own network stack: its own eth0, its own loopback, its own routing table. Port 8080 inside the container is entirely distinct from port 8080 on the host until you map it with -p 8080:8080.

Mount, UTS (hostname), IPC, and user namespaces round out the set. All of them are Linux kernel calls — unshare(2) is the syscall; unshare --pid --fork --mount-proc bash gives you a primitive container in one command.

2

cgroups — what the process can use

Control groups enforce resource accounting and limits. docker run --memory=512m --cpus=1.5 translates to kernel cgroup entries that throttle the container's memory and CPU scheduling. When TraceLab's ingestion worker OOMs, it's the cgroup memory limit triggering the OOM killer — not the host going out of memory. cgroups bound the blast radius; without them, one rogue container can starve everything else on the host.

Linux has two cgroup versions (v1 and v2); modern distributions default to v2. Docker respects both. You can inspect a running container's cgroup path: cat /proc/1/cgroup inside the container will show something like /system.slice/docker-<sha>.scope.

3

Union filesystem — the layered image

This is the part that makes the Docker image format elegant. The root filesystem of a container is assembled by stacking immutable layers on top of each other using a union mount (OverlayFS on most systems). Each layer is a set of filesystem deltas — files added, modified, or removed relative to the layer below. A running container gets one additional writable layer on top; writes go there, not to the image layers. When the container stops, that writable layer is discarded unless you commit it (which you should almost never do in production).

Namespaces what it can see PID · Network Mount · UTS · IPC User syscall: unshare(2) cgroups what it can use memory · cpu · cpuset blkio · net_cls limits + accounting v2: unified hierarchy OverlayFS the layered image writable layer (ephemeral) app layer (RO) deps layer (RO) base OS layer (RO) same Linux kernel as the host — no hypervisor, no second boot
Docker is a Linux process shaped by three kernel features. All three must be present for a container to start; the failure mode when one is absent is usually an error about kernel capabilities, not Docker.
⚠ Containers and VMs are not the same security boundary

A VM runs on a hypervisor that presents virtualized hardware. A kernel exploit in the guest still requires escaping the hypervisor. A container shares the host kernel — a kernel exploit in the container is a host-level exploit. The namespace walls are permission walls, not hardware walls. Running untrusted workloads in containers is a different threat model from running them in VMs. For TraceLab's use case (trusted experiment code) containers are fine; for a shared research cluster running arbitrary user notebooks, this matters.

CORE CONCEPTImages as stacked immutable layers

Every RUN, COPY, and ADD instruction in a Dockerfile produces one layer. Layers are content-addressed (SHA-256 of their tar archive), immutable once written, and cached by the build daemon. When you rebuild, Docker checks each layer's cache key. If the key matches, it reuses the cached layer and skips the work. If any instruction changes, all layers below it in the build get invalidated — the cache cascade.

The cache key for a COPY instruction is the checksum of the files being copied. A RUN instruction's cache key is the instruction text plus the state of the layer above it. This has a profound practical consequence:

🔑 COPY ordering is everything

If you COPY . . (copy all your source) before RUN pip install, then every single source file change — editing a comment, tweaking a log message — invalidates the pip layer. The dependency install re-runs from scratch on every build. For TraceLab's ~60-package dependency tree this is minutes of cold network fetches. The fix is to copy only what the installer needs first, install dependencies, then copy the application source.

Dockerfile — wrong ordering (naive)cold on every build
FROM python:3.12-slim
WORKDIR /app

# BAD: copies ALL source first — every .py edit busts the pip cache
COPY . .
RUN pip install --no-cache-dir -r requirements.txt

CMD ["python", "tracelab/server.py"]
Dockerfile — correct ordering (layer discipline)deps cached until requirements change
FROM python:3.12-slim
WORKDIR /app

# GOOD: copy only the manifest first → install → then copy source
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Source changes only bust from here — deps layer stays cached
COPY . .

CMD ["python", "tracelab/server.py"]

Beyond ordering, the other major image size driver is the base image choice. python:3.12 is Debian bookworm with a full package manager, compiler toolchain, and locale data — around 1 GB before you add a single package. python:3.12-slim strips most of that to ~150 MB. python:3.12-alpine goes further to ~55 MB (Alpine base is ~7 MB, but Python's interpreter and standard library add ~48 MB) but uses musl libc, which can break C-extension packages like NumPy and SQLite. For TraceLab, slim is the right tradeoff.

SEE ITImage layer builder — compose, reorder, shrink

The widget below builds TraceLab's Dockerfile instruction by instruction and shows layers accumulating with their sizes. Reorder a COPY above its dependency install and watch the cache invalidation cascade. Then switch to multi-stage mode and watch the image shrink from 1.2 GB to ~150 MB.

⚙ Interactive · Dockerfile layer builder

Select a build mode, then click Add next instruction to stack layers one at a time. Watch cache status change when you reorder COPY.

Image size: 0 MB
Instruction
—
Cache result
—
Build time (relative)
—
Layers so far
0

Choose a build mode and start adding instructions.

The size difference is real: the naive build ships the full Debian toolchain (gcc, make, header files) into the final image because pip install compiles some packages. The multi-stage build discards that stage entirely and copies only the compiled wheels into a fresh slim base. The container that runs in production contains none of the build tooling — a smaller attack surface and a smaller pull.

TRACELABTraceLab v4 — containerized with layer discipline

TraceLab's stage 5 milestone is called "shipped and survived." Containerization is the first step: the experiment goes from a Python script on a laptop to an artifact that runs identically in CI, on a staging server, and in production. Here is the production Dockerfile we build toward, with every decision annotated.

DockerfileTraceLab v4 production
# ── Stage 1: build ─────────────────────────────────────────────────────────
# Use a full image with compiler toolchain for packages that need C extensions
FROM python:3.12-slim AS builder

WORKDIR /build

# Layer discipline: manifest only → install → no source in build cache key
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

# ── Stage 2: runtime ────────────────────────────────────────────────────────
# Fresh base — no build toolchain, no pip cache, no /build artifacts
FROM python:3.12-slim

# Non-root user — containers should never run as root in production
RUN useradd --uid 10001 --create-home tracelab

WORKDIR /app

# Copy compiled deps from builder (skips all build tooling)
COPY --from=builder /install /usr/local

# Copy source — this layer is the only thing that changes per commit
COPY --chown=tracelab:tracelab tracelab/ ./tracelab/

# Runtime config via env — never bake secrets into the image
ENV TRACELAB_ENV=production \
    PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

USER tracelab

# Explicit port documentation (EXPOSE does not publish — it is documentation)
EXPOSE 8080

# Health check — the orchestrator uses this, not just documentation
HEALTHCHECK --interval=30s --timeout=3s \
  CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8080/health')"]

CMD ["python", "-m", "tracelab.server"]

Six decisions, each earned by a production failure somewhere:

DecisionWhat it prevents
Separate build and runtime stagesCompiler, headers, and pip cache (~1 GB) never reach the running container
COPY requirements.txt before sourceSource edits don't bust the pip install layer — builds stay fast
--prefix=/install + COPY --from=builderClean separation between "things installed" and "builder filesystem"
Non-root USER tracelabA container escape or path traversal runs as an unprivileged UID, not root
ENV … PYTHONUNBUFFERED=1Log lines are not buffered in the process — they reach stdout immediately, visible to the container runtime
HEALTHCHECKKubernetes / Docker Compose marks the container unhealthy and restarts it rather than routing traffic to a frozen process
💡 .dockerignore is as important as Dockerfile

If you don't have a .dockerignore, COPY . . sends your .git/ directory, your __pycache__, any .env files, and your local runs.csv data into the build context — and then into the image layer. The .dockerignore file follows the same syntax as .gitignore. At minimum: .git, *.pyc, __pycache__, *.env, runs.csv, and any local data directories.

IN PRACTICEMulti-stage builds: the size is in the tooling

The pattern used above — separate builder and runtime stages in one Dockerfile — is the main lever for keeping images small. The insight is that the things you need to build your software (compilers, header files, build tools, test runners) are completely different from what you need to run it (the compiled artifacts and their runtime dependencies).

For a Python service the saving is dramatic only when packages include C extensions. Pure-Python packages install as wheels that are already compiled on PyPI's build servers — the pip install in the builder stage just unpacks them. But packages like psutil, pydantic (when Rust acceleration is enabled), or anything that links against a system library like libpq will trigger a compile step that needs gcc and system headers. That compiler, and everything it pulls in, is the source of the 1 GB overhead. The multi-stage build discards that entire stage.

shellverify image sizes
# Build the naive version
docker build -t tracelab:naive -f Dockerfile.naive .
docker image ls tracelab:naive
# → tracelab   naive   sha256:…   1.21GB

# Build the multi-stage production version
docker build -t tracelab:prod .
docker image ls tracelab:prod
# → tracelab   prod    sha256:…   153MB

# Inspect layers to see what contributed size
docker history tracelab:prod

Beyond Python, the multi-stage pattern shines hardest for compiled languages: Go's builder stage contains the entire Go toolchain; the runtime stage can be scratch (an empty filesystem) plus the single statically-linked binary. The resulting image is 10–20 MB. This is the endgame of the pattern: the artifact you ship contains exactly what the process needs to run, nothing it needed to become.

📖 docker build --no-cache is for debugging, not production CI

Running --no-cache on every CI build defeats the entire purpose of layer caching. The right model is to let the cache work normally in CI using a registry-backed cache (--cache-from pointing at the previous build's image tag). Reserve --no-cache for diagnosing "why is my image still using old code" — which is almost always a cache-key problem you should fix in the Dockerfile, not defeat by disabling the cache.

WEAKNESSWhere containers bite

✗ COPY ordering that makes every build cold

The most common Docker performance mistake: COPY . . at line 3, pip install at line 4. Every source file change — a docstring tweak, a comment fix — invalidates the entire pip layer. On a project with heavy dependencies (PyTorch, anything with C extensions), this can mean 5–10 minutes of cold rebuilds instead of 30-second cached ones. The fix is mechanical: copy only what the installer reads first, install, then copy the rest. This is not an optimization you add later; it costs nothing to do right the first time.

✗ 1.2 GB images shipped to production

A 1 GB image is not just a storage cost — it's a pull latency cost at every deployment, a cold-start penalty when an instance scales up under load, and a larger attack surface (every package in the image is a potential vulnerability). The python:3.12 base image ships with gcc, binutils, perl, and a full package manager. None of those are needed to run a Python web service. python:3.12-slim cuts ~850 MB from day one. The decision to use the full image "because it's simpler" is a choice you will re-examine the first time a security scanner flags 400 CVEs in packages you don't use.

✗ The false belief that a container is a security boundary

The namespace isolation is real but its limits are serious. Capabilities: a container running as root with --privileged can remount filesystems, load kernel modules, and reach most of the host. Even without --privileged, several default capabilities (like CAP_NET_ADMIN) can be exploited. Kernel attack surface: the container calls directly into the host kernel with the same interface as any other process; a container-escape exploit against a kernel vulnerability gives an attacker root on the host. Shared namespaces: mounting the host PID namespace, docker socket, or /var/run/docker.sock inside the container gives it near-total control of the host. Running containers as non-root (USER 10001), dropping capabilities, and never mounting the docker socket are hygiene, not paranoia.

KEY INSIGHTHow this connects

  • Environments, Config, and Secrets (5.1) — the lesson that set up the problem this one solves: environment parity breaks because dev and prod have different installs. The Dockerfile makes the environment explicit and reproducible. Config and secrets stay out of the image — passed in at runtime via env vars, as Lesson 5.1 specified.
  • CI: Trust Through Automation (5.3) — the next lesson wires the Dockerfile you just learned to write into a CI pipeline that builds, tests, and pushes the image on every commit. The layer cache discipline from this lesson is what makes that pipeline fast enough to be useful.

The container is TraceLab's first reproducible artifact — the thing you can hand to another machine and have it run correctly. Everything else in Stage 5 builds on that: the CI pipeline builds the artifact, the infrastructure code declares where it runs, the observability tools peer inside it, and the SLOs measure whether it's behaving. A container without understanding its failure modes is infrastructure folklore; with this lesson's model, it's a deliberate engineering choice.

GLOSSARYKey terms introduced

Namespace (Linux)
A kernel feature that gives a process a private view of a global resource — PID tree, network stack, filesystem root, hostname — so it cannot see or interfere with other namespaces.
cgroup (control group)
A kernel mechanism for accounting and enforcing resource limits (memory, CPU, I/O) on a group of processes; Docker uses cgroups to implement --memory and --cpus flags.
OverlayFS
A union filesystem that presents multiple directory trees as one by stacking a writable "upper" layer over one or more read-only "lower" layers; the backing technology for Docker image layers on most Linux systems.
Image layer
An immutable, content-addressed tar archive of filesystem deltas produced by one Dockerfile instruction; layers are cached and reused across builds when their cache key is unchanged.
Cache invalidation (build)
When a Dockerfile instruction's cache key changes, all subsequent layers must be rebuilt; COPY ordering determines how frequently this cascade is triggered.
Multi-stage build
A Dockerfile pattern using multiple FROM … AS stage blocks; the final image copies only artifacts from prior stages, discarding build tooling and intermediate files.
Non-root container
A container whose process runs as a non-zero UID; a security hygiene practice that limits the damage radius of a container escape or path traversal exploit.
HEALTHCHECK
A Dockerfile instruction that tells the container runtime how to probe whether the application inside the container is responding; used by orchestrators to determine when to restart or stop routing traffic to a container.

ACTIVE RECALLCheck your understanding

Answer in your own words first, then reveal.

1What are the three Linux kernel features that make a Docker container work, and what does each one provide?›

Namespaces restrict what the process can see: its own PID tree, network stack, filesystem root, and hostname. cgroups limit and account for what it can use: memory, CPU, and I/O. OverlayFS (or another union filesystem) assembles the layered image as the container's root filesystem, stacking immutable read-only layers with a single writable top layer. Docker wraps these three kernel features with a build format and a registry protocol — it did not invent new isolation technology.

2Why does a COPY . . before RUN pip install make every build cold, and how do you fix it?›

The cache key for a COPY layer is the checksum of the files being copied. If you copy all source first, any source change — a comment, a log message, a type hint — changes the checksum, busts that layer's cache, and forces every subsequent layer (including the pip install) to rebuild. The fix: COPY requirements.txt . first, then RUN pip install, then COPY . .. Now the pip layer's cache key only changes when requirements.txt changes, not on every source edit. Dependency installs become warm in seconds instead of cold over minutes.

3Why is "a container is a security boundary" false, and what makes it meaningfully different from a VM?›

A VM sits behind a hypervisor that virtualizes hardware; a kernel exploit inside the VM still needs to escape the hypervisor. A container shares the host kernel directly — all container syscalls reach the same kernel code as the host. A kernel vulnerability exploitable from inside a container is a host-level exploit. Beyond kernel exploits, containers running as root with default capabilities can do real damage: mounting host filesystems, loading kernel modules, or accessing the docker socket gives near-total host control. The mitigations — non-root USER, dropping capabilities, no docker socket mount — are necessary, not optional.

4What does a multi-stage Dockerfile build accomplish, and why does it shrink TraceLab's image from 1.2 GB to ~150 MB?›

A multi-stage build uses two (or more) FROM blocks in one Dockerfile. The builder stage has the full compiler toolchain and pip cache for compiling C-extension packages. The runtime stage starts from a fresh slim base and copies only the installed Python packages from the builder — discarding gcc, binutils, the pip cache, header files, and the entire builder filesystem. The size difference (~1 GB) is almost entirely the Debian build toolchain that compiles packages like psutil. The container that ships to production contains none of it: smaller pull, smaller attack surface, faster cold start.

Next: wire the Dockerfile into a CI pipeline that gates on your test suite →