System Atlas
the atlas

How Docker works

Package an app and everything it needs into one portable, isolated unit.

the gist

Docker packages an app plus its dependencies into an image that runs as an isolated container sharing the host kernel — far lighter than a full VM. You write a Dockerfile, `docker build` bakes it into a layered, cached image, push it to a registry, and `docker run` launches a container. The client talks to the Docker daemon, which does the building and running.

ANALOGY // A shipping container: pack your goods once, and any ship, crane or truck can carry it without caring what's inside — the container is the standard interface.
living diagram01 / 06
Dockerfilebuild recipedocker buildvia daemonImagelayered · cachedRegistrypush / pulldocker runvia daemonContainerisolated · host kernel
01

Write a Dockerfile

You describe the app's base image, dependencies, files and start command in a Dockerfile — a plain, repeatable recipe. Each instruction (FROM, COPY, RUN, CMD) is deliberate because it becomes a cached layer in the final image. This text file is the single source of truth for how the environment is assembled, so the same recipe reproduces the same result anywhere.

02

docker build

The client sends the Dockerfile and build context to the daemon, which executes each instruction in order, committing the result of each as a stacked layer. Unchanged layers are pulled from cache instead of rebuilt, so editing your last line rebuilds in seconds rather than from scratch. The output is a content-addressed image tagged with a name you choose.

03

The image

The result is an immutable, layered image — a read-only snapshot of the app and everything it needs to run, from the OS libraries up. Because layers are shared and deduplicated, ten images built on the same base cost far less disk than ten full copies. The image is inert on its own: it is a template, not a running process.

04

Push to a registry

You push the image to a registry (Docker Hub, ECR, GHCR) so other machines can pull the exact same artifact by name and tag. Only layers the registry doesn't already have are uploaded, keeping transfers small. This is how a build produced on a laptop or CI runner travels unchanged into staging and production.

05

docker run

On any host, `docker run` tells the daemon to pull the image if it isn't local, then create a thin writable layer on top and start the process defined by the image. Flags wire up ports, volumes, environment variables and resource limits at launch time. The same image can be run many times to produce many independent containers.

06

The container

The container runs as an ordinary process on the host, but Linux namespaces give it its own private view of the filesystem, network, and process tree, while cgroups cap its CPU and memory. It shares the host kernel rather than booting its own OS, which is why it starts in milliseconds and stays lightweight. When it exits, its writable layer can be discarded, leaving the image untouched.

the full picture
01

The problem: "but it works on my machine"

Every developer eventually ships code that runs perfectly on their laptop and then falls over in test or production. The cause is almost always the environment: a different version of Python or Node, a missing system library, an environment variable that only exists locally, a different OS. The application code is identical, but the surroundings it depends on are not, and software is only as reproducible as everything underneath it.

The traditional fixes were painful. Detailed setup docs drift out of date the moment someone forgets a step. Configuration-management tools like Ansible or Chef script the setup, but they mutate a long-lived server whose state slowly diverges from every other server. Full virtual machines guarantee a consistent environment by shipping an entire guest operating system, but a VM is gigabytes in size and takes tens of seconds to boot, which is far too heavy to run one per service.

Docker's insight is to package the application together with its dependencies into one portable unit — the image — and then run that unit in a lightweight, isolated sandbox — the container. The environment stops being something you configure on the destination and becomes something you build once and carry with the app. "Works on my machine" becomes "works, because the machine travels with it."

02

Images vs containers: the core distinction

The two words people conflate are the two things you most need to keep separate. An image is a read-only template: a frozen snapshot of a filesystem plus metadata (the default command, exposed ports, environment). A container is a running (or stopped) instance created from an image, with a thin writable layer on top where its runtime changes live.

The relationship mirrors classes and objects, or a program on disk versus a process in memory. One image can spawn many containers, each isolated from the others; each container can be started, stopped, and thrown away without affecting the image it came from.

  • An image is built, versioned, tagged, and distributed. It never changes once created — it is immutable.
  • A container is created, run, and destroyed. Its writable layer is ephemeral by default: delete the container and those changes are gone unless you mounted a volume.

This is why the guidance is to treat containers as cattle, not pets — disposable and interchangeable. Anything you need to survive a container's death (a database's data, uploaded files) must live outside its writable layer in a mounted volume. Getting this distinction right is what makes containers reproducible instead of just another mutable box.

03

The layered filesystem and build cache

An image is not one monolithic blob; it is a stack of read-only layers, each produced by one instruction in the Dockerfile and combined at runtime by a union filesystem (overlayfs) that presents them as a single merged tree. A FROM node:20 line is one layer, COPY package.json . another, RUN npm install another, and so on.

Two properties fall out of this design and they are the whole point:

  • Sharing. Layers are content-addressed and deduplicated. If twenty images all start FROM ubuntu:22.04, that base is stored once on disk and pulled once over the network. This is what keeps images cheap despite bundling an OS userland.
  • Caching. During a build, Docker reuses a cached layer whenever the instruction and its inputs are unchanged. The corollary drives Dockerfile ordering: put rarely-changing steps (installing dependencies) before frequently-changing ones (copying your source). If you COPY your whole app before npm install, every code edit busts the cache and reinstalls everything; split them and a code change only rebuilds the final, tiny layer.

When you push an image, the registry already has most base layers, so only your new layers travel. The layered model is simultaneously the storage format, the caching mechanism, and the transfer optimisation.

04

The lifecycle end to end: Dockerfile → build → registry → run

A container's life is a short, well-defined pipeline, and knowing each handoff makes the whole system legible.

  • Dockerfile. A text recipe declaring the base image, the files to copy in, the commands to run at build time, and the default command to run at start. It is the reproducible definition of the environment.
  • `docker build`. The Docker client ships the Dockerfile and build context to the daemon (dockerd), which executes each instruction, committing a layer per step, and tags the resulting image. The client is just a thin front end — the daemon does the real work, which is why remote and CI builds look identical to local ones.
  • Registry. docker push uploads the image to a registry — Docker Hub, Amazon ECR, GitHub's GHCR — the shared "pantry" that lets any host retrieve the exact same artifact by name:tag.
  • `docker run`. On the target host, the daemon pulls the image if absent, adds a writable layer, sets up isolation, and launches the image's command as a container. Ports, volumes, env vars, and CPU/memory limits are all wired up here at launch.

The critical discipline is build once, run anywhere: the identical image that passed tests is the one promoted to production. Nothing is rebuilt downstream, so there are no "it recompiled differently" surprises between environments.

05

How isolation works — and why it beats a VM

A container feels like a separate machine but is really just a normal Linux process wearing three pieces of kernel machinery:

  • Namespaces give the process a private view of the system. A PID namespace makes its processes start at PID 1 and hides the host's; a mount namespace gives it its own filesystem root; network, UTS, and user namespaces isolate its network stack, hostname, and user IDs. The process literally cannot see what isn't in its namespaces.
  • cgroups (control groups) meter and cap what it can consume — CPU shares, memory ceilings, I/O bandwidth — so one container can't starve its neighbours.
  • The union filesystem stitches the image's read-only layers plus the writable layer into the root it sees.

The decisive fact is that all containers share the host's kernel. There is no guest OS to boot, no virtual hardware to emulate. That is why a container starts in milliseconds and weighs megabytes, while a VM boots in tens of seconds and weighs gigabytes because it carries a full operating system per instance.

The trade-off is the flip side of that sharing: containers offer weaker isolation than VMs. A kernel vulnerability is a shared attack surface, and you can't run a genuinely different kernel (Windows containers on a Linux host, say) without a VM underneath. For most workloads the speed and density win easily; for hard multi-tenant security boundaries, people layer lightweight VMs (Firecracker, Kata) under the containers to get both.

06

Failure modes, real-world usage, and guidance

Docker rarely fails mysteriously, but it fails in predictable ways worth naming. Losing data is the classic beginner mistake: writing to the container's own filesystem and then wondering where it went after a redeploy — state must go in a volume or an external store. Bloated images come from installing build tools you don't need at runtime; the fix is multi-stage builds, where a heavy "builder" stage compiles the app and a slim final stage copies out only the artifact. Cache-busted builds that reinstall everything on each commit trace back to Dockerfile ordering. And running as root inside the container is a needless risk — set a non-root USER.

In practice Docker is the substrate the rest of modern delivery sits on. CI pipelines build an image on every commit as the versioned artifact they test and promote. Orchestrators like Kubernetes assume containers as their unit of deployment and add scheduling, self-healing, and scaling on top. Local development uses docker compose to spin up an app plus its database and cache with one command that matches production.

Practical guidance for a first-timer:

  • Pin base image tags (node:20.11, not node:latest) so builds are reproducible.
  • Keep images small and single-purpose — one process per container.
  • Never bake secrets into an image; inject them at run time.
  • Put slow, stable steps early in the Dockerfile and volatile steps last.

Get those habits right and Docker delivers its core promise: the environment stops being a variable, and what ran on your laptop is exactly what runs in production.

what to remember
01

An image bundles the app and its dependencies; a container is a running, isolated instance of that image.

02

Containers share the host kernel, so they start in milliseconds and cost far less than a VM.

03

A Dockerfile is the build recipe; `docker build` turns it into an image made of cached, stackable layers.

04

A registry (like Docker Hub) stores and distributes images so any host can pull and run them.

05

The Docker client is just a front end — the daemon (dockerd) actually builds images and runs containers.

check yourself

Quick quiz

Q1

Why is a container lighter than a virtual machine?

Q2

What does `docker build` actually produce?

follow the thread