The On-Disk Stores
In one sentence: The engine persists its world in four small databases — a reference store (names → digests), an image store (configs), a layer store (extracted diffs), and a container store (instances) — each owning exactly one question.
You already know
- From Lesson 7: tags resolve to manifests, manifests to configs and layers.
- From Lesson 9: layers must be extracted to directories before they can be overlay-mounted.
One question per store
Persistence gets simple when each store answers one question. Reference store: "what digest does this name point to?" — a tiny mutable map, the only place where names live. Image store: "what is this image's config and layer list?" — immutable, digest-keyed. Layer store: "where is this layer extracted on disk, and who is its parent?" — it stores chains, because layer 3 extracted on top of layers 1–2 is a different filesystem than layer 3 alone. Container store: "what containers exist, from which image, in what state?" — the only store that changes at runtime.
flowchart LR
E["engine"]
RS[("reference store
name → digest")]
IS[("image store
digest → config + layer list")]
LS[("layer store
diff → extracted dir + parent chain")]
CS[("container store
id → image, state, mounts")]
E -- "resolve names" --> RS
E -- "read configs" --> IS
E -- "mount chains" --> LS
E -- "track instances" --> CS
RS -. "points into" .-> IS
IS -. "references" .-> LS
CS -. "instantiated from" .-> IS
One command, four lookups
sequenceDiagram
participant C as CLI
participant E as Engine
participant RS as Reference store
participant IS as Image store
participant LS as Layer store
C->>E: list images
E->>RS: all name → digest entries
RS-->>E: api:2.1 → sha256:9f3c…, web:1.0 → sha256:77aa…
E->>IS: config for each digest
IS-->>E: created-at, layer lists
E->>LS: total size of each layer chain
LS-->>E: sizes (shared layers counted once)
E-->>C: table: name, id, created, size
Anchor these
- Four stores, four questions: names, configs, extracted layers, instances.
- Only the reference store is name-keyed and mutable; image/layer stores are digest-keyed and immutable.
- The layer store tracks parent chains — an extracted layer only makes sense atop its parents.
See what actually stuck.
Take the practice scenarios now.