storage • Advanced

OverlayFS & Layered Image Architecture (lowerdir vs upperdir)

Docker images are composed of read-only immutable layers (lowerdir) combined with a thin read-write container layer (upperdir). OverlayFS presents a unified merged filesystem view via Copy-on-Write (CoW).

Intuitive Mental Model

The Overhead Projector Transparencies: Each Dockerfile command is a clear transparent plastic sheet printed with ink (read-only lowerdir). When stacked together, you see the complete picture. When you write a file in the container, you draw with a dry-erase marker on the top glass sheet (upperdir).

Dockerfile / YAML Manifest / CLIProduction Standard

# Dockerfile layer caching order:
FROM node:22-alpine AS base
WORKDIR /app

# Layer 1 (Cached unless package.json changes):
COPY package*.json ./
RUN npm ci --only=production

# Layer 2 (Frequently changing source code):
COPY . .

# OverlayFS Directory Hierarchy:
# lowerdir = Read-only image layers (node runtime + npm dependencies)
# upperdir = Container read-write layer (log files, /tmp writes)
# merged = Unified view visible inside the container at /

Key Architectural Takeaways

•Copy-on-Write (CoW): Modifying a file from a lower layer copies the entire file into the upperdir before writing.
•Immutable Layers: Multiple running containers based on the same image share 100% of read-only lowerdir layers in RAM, saving gigabytes of disk and page cache.
•Deleting a file in a container creates a "whiteout" character device in upperdir, masking the file in merged view without deleting it from the base image.

Common Production Mistake

Installing build tools and deleting them in a subsequent RUN command (e.g. RUN apt-get install && RUN apt-get remove), which still permanently retains the files in previous lowerdir layers.