Vibe Engines
YouTube

Vibe Engines is free, interactive AI engineering & system design — runs in your browser. Pick a learning path

Handbooks  /  Docker
Engineering~12 min readBeginner-friendly
Deep Dive

Docker: a container is a lie told by the kernel.

"Works on my machine" died because we learned to ship the machine. But the machine we ship isn't a virtual computer — it's an ordinary process wearing an elaborate disguise, and the disguise is maintained by the host kernel. Understand that one trick and images, layers, volumes and networking all fall into place.

01

Not a VM: namespaces + cgroups

A virtual machine virtualizes hardware and boots its own kernel — heavyweight by construction. A container virtualizes nothing. It's a normal Linux process (or process tree) that the kernel systematically deceives via two mechanisms:

The two kernel features that ARE containers
NamespacesLimit what the process can SEE: its own process table (it thinks it's PID 1), network stack, mount table, hostname, IPC and, optionally, user IDs. One lie per namespace type.
cgroupsLimit what it can USE: CPU shares, memory ceilings, IO bandwidth. The reason one greedy container can't starve the host.

That's why containers start in milliseconds (nothing boots — a process forks), share the host's memory efficiently, and can be packed by the hundred onto one box. It's also why Linux containers need a VM shim on Mac/Windows — the lies are Linux-kernel lies. Docker's real invention wasn't the container; the kernel had the pieces. It was the packaging — which brings us to images.

02

Images: a filesystem in layers

An image is the filesystem the lie will present — built as a stack of read-only layers, one per filesystem-changing instruction (RUN, COPY, ADD; the others only set metadata), each recording only the changes it made. Layers are content-addressed (Git vibes, deliberately): ten images built on the same Ubuntu base share those bytes once, on disk and in the registry. When a container runs, a thin writable layer goes on top; the image below stays immutable, which is why a container is disposable by design — kill it and the writable layer is all that dies.

→ The rule that halves your build times

The build cache reuses layers top-down until the first instruction that changed — everything after rebuilds. So order Dockerfiles by volatility: dependencies first (change rarely), source code last (changes constantly). COPY package.json → RUN npm install → COPY . . exists precisely so editing your code doesn't reinstall your dependencies.

03

Dockerfiles that ship small

The classic sins: bloated images carrying compilers into production, root processes, latest-tag roulette. The fixes are few and mechanical:

PracticeWhy
Multi-stage buildsbuild in a fat stage, COPY --from=build only the artifact into a slim final stage — GBs → tens of MBs
Small bases-slim / distroless / alpine (mind musl quirks) — less surface, faster pulls
Pin versionsFROM node:22.4, never :latest — builds you can reproduce next year
Non-root USERcontainer escape from root is host trouble; from uid 1000 it's a shrug
.dockerignorekeep node_modules, .git and secrets out of the build context entirely
One process per containerthe unit of scaling, logging and restart — compose processes, don't bundle them

The one that saves the most time is layer order. The build cache reuses a layer only if it and everything above it are unchanged, so the first changed instruction busts the cache for itself and all layers below:

cached ⟺ this line and every line above it unchanged  →  first change rebuilds itself + everything after

Put COPY . . before RUN npm install and a one-line code edit re-runs the whole install (~60s); put it after and the same edit costs ~2s. The runnable version below builds both orders and prices the rebuild.

04

A production Dockerfile, line by line

Every line below earns its place: cache order, a slim final stage, a non-root user and a start command that receives signals.

# syntax=docker/dockerfile:1
FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY . .
RUN npm run build

FROM node:22-slim
ENV NODE_ENV=production
WORKDIR /app
COPY --from=build /app/package.json /app/package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
EXPOSE 3000
ENTRYPOINT ["node"]
CMD ["dist/server.js"]

In both stages the manifests are copied and installed before the source or the built output, so a code edit reuses the install layer. The build stage keeps the compiler and dev dependencies and never ships; the final stage gets only the built output plus production dependencies. USER node drops root (the official Node image creates that user). EXPOSE only documents the port; publishing is still -p.

BuildKit cache mounts. RUN --mount=type=cache gives that one command a persistent directory that is never written into the image. The package manager's download cache survives between builds, so when a manifest changes and the install layer must rebuild, npm still reuses downloads from earlier builds. A type=secret mount does the same for credentials: the file exists during one RUN and appears in no layer or image history. BuildKit is the default builder in current Docker releases.

ENTRYPOINT vs CMD, and why the form matters

InstructionRoleOverridden by
ENTRYPOINTthe executable the container runsdocker run --entrypoint
CMDdefault arguments, or the whole command if there is no ENTRYPOINTanything after the image name in docker run

With the file above, docker run app runs node dist/server.js and docker run app dist/worker.js runs node dist/worker.js. Write both in exec form, a JSON array. Shell form (CMD npm start) wraps your command in /bin/sh -c, so the shell becomes the container's main process and your app is its child.

That matters because of PID 1. The first process in a container's PID namespace is PID 1, and the kernel does not apply default signal actions to it: a SIGTERM with no handler installed is ignored. docker stop sends SIGTERM, waits 10 seconds by default, then sends SIGKILL, so a program that never handles SIGTERM takes ten seconds to stop and exits with code 137. PID 1 must also reap orphaned child processes, or zombies pile up. Fix it by handling SIGTERM in your code, or run a tiny init that forwards signals and reaps children: docker run --init, or tini as the ENTRYPOINT.

05

What actually runs your container

docker run is the front of a chain. The CLI calls the Docker daemon, dockerd, which hands container lifecycle to containerd. containerd pulls and unpacks images and starts each container through a small shim process, which in turn invokes runc. runc creates the namespaces and cgroups, sets up the root filesystem, then executes your process and exits; the shim stays behind to hold the container's stdio and report its exit. Kubernetes skips the Docker daemon and talks to containerd (or CRI-O) directly.

The seams between those pieces are open standards from the Open Container Initiative: the image spec (layers plus a config), the runtime spec (a root filesystem plus a config.json that runc consumes) and the distribution spec (how registries serve images). That is why an image built with Docker runs under Podman or containerd unchanged.

Layers on disk. The common storage driver, overlay2, uses Linux overlayfs. The image layers are stacked read-only lower directories, the container's writable layer is the upper directory, and the container sees the merged view. The first time a container writes to a file that lives in a lower layer, the whole file is copied up into the writable layer; this copy-on-write makes a one-byte edit to a large file expensive. Deleting a lower-layer file writes a marker called a whiteout, which hides the file but does not shrink the image. For the same reason, RUN rm in a later layer never reclaims space; clean up in the same RUN that created the files. Write-heavy data belongs on a volume, which bypasses overlayfs.

Memory limits and OOM kills. docker run --memory 512m sets a cgroup memory limit. When the container's processes need more than the limit and nothing can be reclaimed, the kernel's OOM killer kills one of them with SIGKILL. The container exits with code 137 (128 + 9), and docker inspect shows State.OOMKilled: true, with no stack trace and no application log line, because the process never got a chance to write one. Runtimes with their own heaps need the limit told to them: set Node's --max-old-space-size below the container limit, and use a JVM version that reads cgroup limits (all current releases do). CPU limits behave differently: a container over its CPU quota is throttled, not killed.

06

State: volumes, and the amnesia feature

Containers forget by design — the writable layer dies with them. That amnesia is a feature (identical fresh state every run) until you're running a database. The escape hatches: volumes (Docker-managed directories mounted into the container — survive restarts, the production answer) and bind mounts (a host directory mapped straight in — the dev-loop answer, your editor writing into the running container). The discipline is knowing which data is cattle (rebuildable — leave it in the container) and which is sacred (the database files — volume, backed up).

07

Networking: who can talk to whom

Each container gets its own network namespace — its own localhost, which is the #1 beginner trap: localhost inside a container is the container, not your machine. Containers on the same user-defined bridge network reach each other by name (Docker runs the DNS: db:5432 just works); the outside world reaches a container only through explicitly published ports (-p 8080:80 — host:container). That's 90% of Docker networking: name-based reach within a network, port-mapping at the edge, and nothing visible unless you published it.

08

Compose, and the handoff to Kubernetes

Real apps are several containers — API, database, cache, worker. Compose is the one-machine orchestrator: a YAML file declaring services, networks and volumes, brought up with one command, networked by name automatically. It is the standard dev environment and a perfectly honest small-deployment tool.

services:
  api:
    build: .
    ports:
      - "8080:3000"
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/app
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 5s
      timeout: 3s
      retries: 10
volumes:
  pgdata:

One docker compose up builds the API image, starts Postgres with its data on a named volume, and puts both on a default network where the API reaches the database at db:5432. Only port 8080 is published to the host. depends_on alone orders container start, not readiness; the service_healthy condition makes the API wait until the health check passes. The inline password is for local development only; use an env file or secrets anywhere else.

What Compose doesn't do is fleet: many machines, self-healing, rolling deploys, autoscaling. That's Kubernetes — same containers, a much bigger brain around them. The pipeline in practice: Dockerfile → image → registry → Compose (dev) → Kubernetes (prod), with the image as the invariant artifact moving through it. Master the image and the rest is configuration.

RUN IT YOURSELF

Price a rebuild: layer order is everything

The Docker build cache reuses a layer only if it and every layer above it are unchanged — so the first changed instruction rebuilds itself and everything after it. This builds the same app two ways after a one-line code edit. In the bad order, COPY . . sits above RUN npm install, so the edit re-runs the whole 60-second install. In the good order, the install is cached and only the copy rebuilds — the same edit for ~2 seconds. Change which layers are marked changed, or their costs.

CPython · WebAssembly
By the numbers

Worked example: tracing the cache through the page’s Dockerfile

Take the production Dockerfile above and edit one source file. A layer is reused only if its own inputs and its parent layer are unchanged. Walk both stages, instruction by instruction.

StepInstructionAfter a source editWhy
1build: FROM, WORKDIRcachednothing above changed
2build: COPY package.json package-lock.json ./cachedmanifests unchanged
3build: RUN npm cicachedparent unchanged: the full install is skipped
4build: COPY . .REBUILDa source file changed
5build: RUN npm run buildREBUILDparent changed
6final: FROM, ENV, WORKDIRcachedindependent of the build stage
7final: COPY --from=build manifestscachedfiles identical, parent unchanged
8final: RUN npm ci --omit=devcachedparent unchanged: the production install is skipped
9final: COPY --from=build /app/dist ./distREBUILDthe built output changed

Step 8 is the page’s own rule applied twice. In the final stage the manifests and npm ci --omit=dev come before COPY --from=build /app/dist ./dist, so a source edit rebuilds only steps 4, 5 and 9. Put the dist copy above the install instead and it busts the install on every code edit: the cache mount softens that (downloads are reused) but npm ci still runs.

Trade-offs

Cost and trade-offs: where state and isolation live

Here Time is speed (start-up or I/O) and Space is the footprint or what persists.

CaseTimeSpaceWhy
Container vs VMMilliseconds: a process forksShares the host kernel and memoryWeaker isolation: a kernel bug is shared by every container on the host.
Writable layerCopy-up on the first write to each lower-layer fileDies with the containerFine for scratch files; wrong for anything write-heavy or precious.
Named volumeNative disk speed, bypasses overlayfsSurvives restarts and rebuildsBackups and migration are your job, not Docker’s.
Bind mountNative on Linux; slower on Mac/Windows, where files cross the VM boundaryLives on the host pathThe dev-loop tool; couples the container to one machine’s layout.
-slim baseFast pullsSmall, still Debian with a shellThe safe default: glibc, so prebuilt binaries just work.
alpine baseFast pullsSmallest common base, with a shellmusl libc: some native modules need rebuilding or behave differently.
distroless baseFast pullsNo shell, no package managerLeast attack surface; you cannot docker exec a shell to debug.

The pattern: every choice that makes a container lighter or more disposable moves something onto you, whether that is backups, debugging tools or kernel trust.

Watch for

Common mistakes

  • Secrets in ARG or ENV

    Build arguments show up in docker history, and ENV values are baked into the image config that anyone with the image can read. Use a type=secret mount at build time and inject secrets at run time.

  • Publishing a port to the world by accident

    -p 8080:80 listens on every host interface, and Docker writes its own iptables rules, which can bypass a host firewall such as ufw. For a local-only service, bind it: -p 127.0.0.1:8080:80.

  • Treating a tag as a pin

    Tags are mutable: node:22.4 can be re-pushed with a new patch underneath. For a build you can truly reproduce, pin the digest (node:22.4@sha256:…) and update it on purpose.

  • apt-get update in its own RUN

    The update layer is cached, so a later edit to the install line reuses a stale package index and can fail or install old versions. Put apt-get update && apt-get install … in one RUN, and clean up in the same RUN.

  • Believing every instruction adds a layer of files

    Only RUN, COPY and ADD add filesystem layers. ENV, WORKDIR, EXPOSE, USER and CMD only change image metadata, so merging them buys nothing. Merging RUN steps that create and delete the same files is what saves space.

In the wild

Where this shows up in production and interviews

  • CI builds

    CI runners usually start with an empty cache, so the layer-order wins vanish unless you export the cache, for example with docker buildx build --cache-to and --cache-from pointing at a registry. Build once, push, and deploy by digest so every environment runs the same bytes.

  • Kubernetes

    The same rules apply one level up. A pod over its memory limit shows OOMKilled and exit 137. Termination sends SIGTERM, then SIGKILL after the grace period (30 seconds by default), so the PID 1 signal handling above decides whether rolling deploys drop requests.

  • Running untrusted code

    Containers share the host kernel, so for code you did not write, teams add a stronger boundary: a user-space kernel such as gVisor, or a micro-VM such as Firecracker. The image format stays the same; only the runtime under it changes.

  • The interview version

    “What happens when you type docker run?” Walk the chain: CLI, dockerd, containerd, shim, runc, then namespaces, cgroups and the overlay filesystem. Follow up with why a container stops slowly (PID 1 and SIGTERM) and why it exits 137 (SIGKILL, often the OOM killer).

Self-check

Check yourself

A container takes exactly 10 seconds to stop and exits with 137. docker inspect shows OOMKilled: false. What happened?

docker stop sent SIGTERM, nothing at PID 1 handled it, and after the 10-second grace period Docker sent SIGKILL (128 + 9 = 137). Typical causes are a shell-form CMD or an app with no SIGTERM handler. Use exec form and handle the signal, or add --init.

Your API container connects to localhost:5432 and cannot reach Postgres running in another container. What is the fix?

Inside a container, localhost is that container’s own network namespace. Put both on the same user-defined network (Compose does this for you) and connect to the service name: db:5432.

With the reordered final stage from the worked example, you edit only README.md. What rebuilds?

If README.md is not in .dockerignore, COPY . . sees changed context, so steps 4 and 5 re-run. BuildKit keys COPY on file contents, so if the build output is byte-identical the final stage can stay cached. Add docs to .dockerignore and nothing rebuilds at all.

A container appends one line to a 2 GB file that came from an image layer. What happens on disk?

overlay2 copies the whole 2 GB file up into the writable layer on the first write, then appends. It is slow and doubles the disk use. Data that is written to belongs on a volume, which bypasses overlayfs.

Frequently asked

Quick answers

Container vs VM?

A VM boots its own kernel on virtual hardware. A container is host-kernel processes inside namespaces (what it sees) + cgroups (what it uses). Milliseconds vs minutes.

How do layers work?

One read-only layer per RUN, COPY or ADD instruction (the others only set metadata), content-addressed and shared across images; a writable layer on top at runtime. Cache reuses layers until the first changed instruction.

What is a multi-stage build?

Build with the fat toolchain in stage one, copy only the artifact into a minimal final stage — small, clean production images.

Compose vs Kubernetes?

Compose orchestrates one machine (dev, small deploys). Kubernetes orchestrates fleets: self-healing, rolling deploys, autoscaling.

What is the difference between ENTRYPOINT and CMD?

ENTRYPOINT sets the executable a container runs; CMD sets its default arguments, or the whole default command when there is no ENTRYPOINT. Arguments after the image name in docker run replace CMD, and --entrypoint replaces ENTRYPOINT. Write both in the JSON exec form so your process receives signals directly.

What does exit code 137 mean in Docker?

137 is 128 plus 9: the process was killed with SIGKILL. The usual causes are the kernel's OOM killer, after the container exceeded its memory limit, or docker stop giving up when its grace period ran out. docker inspect shows OOMKilled: true in the first case, which tells the two apart.

▶  Watch it explained

What is a container? It's not a VM — it's a fenced-off process

Docker · Engineering · Vibe Engines · 2026
Finished this one? 0 / 209 Handbooks done
NextThe Kubernetes Handbook Next on the “Ship it, then keep it up” ladder · rung 2 of 4

Explore the topic

See this alongside everything else on the same subject — handbooks, system designs, challenges and tools, in one place.

More Handbooks