Docker Filesystem Internals (Advanced)

This post is for readers who already understand Docker basics and want to learn how Docker manages files internally. If you are new to Docker, read the beginner guide first.

Containers Do NOT Have Their Own Disk

A common misunderstanding is that Docker containers have their own disk. In reality:

Containers do not have a separate physical filesystem. Docker creates a filesystem view using layers stored on the host machine.

This layered filesystem is implemented using a Union Filesystem, most commonly OverlayFS on Linux.

Docker Images Are Read-Only Layers

A Docker image is made up of multiple read-only layers. Each instruction in a Dockerfile creates a new layer.

FROM python:3.11
RUN pip install flask
COPY app.py .

This results in layers like:

Layer 1: Base OS + Python
Layer 2: Flask installed
Layer 3: app.py copied

• Layers are read-only
• Layers are cached
• Layers are shared across containers

Containers Add a Writable Layer

When a container starts, Docker adds one writable layer on top of the image:

Writable Container Layer
------------------------
Read-Only Image Layers

Any file changes made by the container go into this writable layer. The original image layers never change.

Copy-On-Write Explained

Docker uses a mechanism called Copy-On-Write.

Example:

• An image contains /app/config.yml
• The container modifies this file

What Docker does:

1. Copies the file from the image layer
2. Places it in the writable layer
3. Modifies the copy

The original image layer remains untouched.

What Happens When a Container Stops?

Action	Result
Stop container	Data remains
Restart container	Data remains
Delete container	Writable layer is deleted

This is why containers are called ephemeral.

Why Containers Are Stateless by Default

Containers are designed to be stateless because:

• The writable layer belongs to the container
• Deleting the container deletes the data
• This enables easy scaling and safe restarts

Volumes: Persistent Data Outside Containers

To store data permanently, Docker provides volumes.

docker run -v mydata:/data my-container

Volumes live outside the container lifecycle and survive container deletion.

Bind Mounts vs Volumes

• Bind mounts: map a host directory into the container
• Volumes: managed by Docker and portable

Both bypass the container’s writable layer.

OverlayFS: One View, Many Layers

OverlayFS merges multiple layers into a single filesystem view. To the container, everything looks like one normal filesystem.

/
├── app/
├── bin/
├── lib/
└── tmp/

Internally, files may exist in different layers, but the container does not know this.

Why This Knowledge Matters

• Debugging missing files
• Understanding data loss after container deletion
• Correct use of volumes
• Kubernetes persistent storage decisions

---

Final Mental Model

Images are immutable layers.
Containers add a temporary writable layer.
Volumes store persistent data outside containers.

Remembering this model means you understand Docker filesystem internals.