Read-only filesystem containers in Docker - Deep Dive

Overview - Read-only filesystem containers

What is it?

Read-only filesystem containers are Docker containers configured so that their file system cannot be changed during runtime. This means no files can be added, modified, or deleted inside the container while it is running. It helps protect the container from accidental or malicious changes. The container can still read files and run programs as usual.

Why it matters

This exists to improve security and stability by preventing unwanted changes inside containers. Without read-only filesystems, containers could be altered by attackers or buggy software, causing unpredictable behavior or data loss. Using read-only containers helps keep environments consistent and safe, especially in production where reliability is critical.

Where it fits

Before learning this, you should understand basic Docker container concepts like images, containers, and volumes. After this, you can explore advanced container security practices, immutable infrastructure, and orchestration tools like Kubernetes that use similar principles.

Mental Model

Core Idea

A read-only filesystem container is like a sealed book: you can read the pages but cannot write or erase anything inside.

Think of it like...

Imagine a library book that you can read but cannot write notes in or tear pages out. The book stays the same for everyone who reads it, just like a read-only container keeps its files unchanged during use.

┌─────────────────────────────┐
│       Docker Container      │
│ ┌─────────────────────────┐ │
│ │ Read-Only Filesystem     │ │
│ │  ┌───────────────────┐  │ │
│ │  │ Files & Programs  │  │ │
│ │  │ (Cannot Modify)   │  │ │
│ │  └───────────────────┘  │ │
│ └─────────────────────────┘ │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Docker Container Filesystems

Concept: Learn how Docker containers use layered filesystems to store data and run applications.

Docker containers use a layered filesystem where the base image layers are read-only, and a writable layer is added on top for changes during container runtime. This writable layer allows files to be created, modified, or deleted inside the container.

Result

You understand that containers normally have a writable layer allowing changes inside the container.

Knowing the layered filesystem structure explains why containers can normally change files and how read-only mode can block that.

2

Foundation

What Does Read-Only Filesystem Mean?

Concept: Introduce the idea of making the container's filesystem read-only to prevent changes.

Setting a container's filesystem to read-only disables the writable layer. The container can still read files from the image layers but cannot create, modify, or delete any files during runtime.

Result

The container runs with a filesystem that cannot be changed, improving safety.

Understanding that disabling the writable layer stops all file changes helps grasp the security benefits.

3

Intermediate

How to Run a Read-Only Container

🤔Before reading on: do you think the read-only option is set inside the Dockerfile or at container run time? Commit to your answer.

Concept: Learn the Docker command option to make a container's filesystem read-only when starting it.

You use the Docker run command with the flag --read-only to start a container with a read-only filesystem. For example: docker run --read-only alpine ls / This runs an Alpine Linux container where the filesystem cannot be changed.

Result

The container starts with a read-only filesystem, preventing file changes during its life.

Knowing that read-only mode is a runtime option allows flexible use without rebuilding images.

4

Intermediate

Using Writable Volumes with Read-Only Containers

🤔Before reading on: do you think volumes inside read-only containers can be writable or not? Commit to your answer.

Concept: Learn how to allow specific parts of a read-only container to be writable using Docker volumes.

Even if the container filesystem is read-only, you can mount Docker volumes or bind mounts as writable directories. For example: docker run --read-only -v /data alpine touch /data/file.txt This lets the container write to /data while the rest stays read-only.

Result

You can selectively allow write access to needed paths while keeping the container mostly immutable.

Understanding writable volumes lets you balance security with necessary container functionality.

5

Intermediate

Common Use Cases for Read-Only Containers

Concept: Explore why and when read-only containers are used in real projects.

Read-only containers are used to: - Increase security by limiting attack surface - Ensure consistency by preventing accidental changes - Run stateless applications that don't need to save data inside - Improve compliance by locking down environments Examples include running web servers, batch jobs, or microservices that only read config files.

Result

You see practical reasons to use read-only containers in production.

Knowing real use cases helps you decide when to apply read-only filesystems effectively.

6

Advanced

Handling Logs and Temporary Files in Read-Only Containers

🤔Before reading on: do you think logs can be written inside a read-only container without special setup? Commit to your answer.

Concept: Learn strategies to manage files that need to be written, like logs or temp files, in read-only containers.

Since the container filesystem is read-only, logs and temp files cannot be written inside by default. Common solutions: - Mount writable volumes for /var/log or /tmp - Use tmpfs mounts (in-memory writable storage) - Redirect logs to external systems Example command: docker run --read-only --tmpfs /tmp alpine touch /tmp/testfile This creates a writable temp directory in memory.

Result

You can run applications that need to write temporary data even with a read-only root filesystem.

Knowing how to handle writable needs prevents failures and keeps containers secure.

7

Expert

Security Implications and Limitations of Read-Only Filesystems

🤔Before reading on: do you think read-only filesystems alone guarantee full container security? Commit to your answer.

Concept: Understand the security benefits and limits of read-only containers in defense strategies.

Read-only filesystems reduce attack surface by blocking file modifications, but they do not stop all attacks. For example, processes with root inside the container can still consume CPU or network resources. Also, writable volumes can be attack vectors if not secured. Combining read-only filesystems with other controls like user namespaces, seccomp, and AppArmor improves security. Experts also watch for subtle issues like writable tmpfs being exploited or misconfigured mounts.

Result

You appreciate read-only filesystems as one layer in a multi-layer security approach.

Understanding the limits prevents overreliance on read-only mode and encourages comprehensive security.

Under the Hood

Docker containers use a layered filesystem called OverlayFS or similar. The base image layers are read-only and shared. Normally, a writable container layer sits on top to record changes. When --read-only is set, Docker disables this writable layer, so the container only sees the immutable base layers. Any attempt to write files fails with permission errors unless volumes or tmpfs mounts provide writable storage.

Why designed this way?

This design leverages Linux kernel features for efficient storage and isolation. The layered approach saves space and speeds up container creation. Making the writable layer optional allows flexibility: developers can choose immutability for security or mutability for development. Alternatives like fully immutable containers were less flexible and harder to use.

┌───────────────────────────────┐
│        Docker Container        │
│ ┌───────────────┐             │
│ │ Base Image    │ (read-only) │
│ ├───────────────┤             │
│ │ Writable Layer│ (disabled  │
│ │  (normal)     │  in read-only)
│ └───────────────┘             │
│ ┌───────────────┐             │
│ │ Volume Mount  │ (optional   │
│ │ (writable)    │             │
│ └───────────────┘             │
└───────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does setting --read-only prevent all changes inside the container, including environment variables and running processes? Commit to yes or no.

Common Belief: Setting --read-only makes the container completely unchangeable in every way.

Reality: It only makes the filesystem read-only. Environment variables and running processes can still change state in memory.

Why it matters: Believing this leads to overconfidence in security and ignoring other attack vectors.

Quick: Can a container with a read-only filesystem write logs inside its root filesystem without extra setup? Commit to yes or no.

Common Belief: Read-only containers can write logs anywhere inside the container as usual.

Reality: They cannot write logs inside the root filesystem unless writable volumes or tmpfs mounts are used.

Why it matters: Ignoring this causes application failures and confusion when logs disappear.

Quick: Does mounting a writable volume inside a read-only container break the read-only guarantee? Commit to yes or no.

Common Belief: Mounting writable volumes inside a read-only container defeats the purpose of immutability.

Reality: Writable volumes are separate from the container's root filesystem and can be controlled independently, allowing selective mutability.

Why it matters: Understanding this helps design secure containers that balance immutability and functionality.

Quick: Is using a read-only filesystem enough to fully secure a container against all attacks? Commit to yes or no.

Common Belief: Read-only filesystems alone make containers fully secure.

Reality: They are one layer of defense but do not prevent all attacks like network exploits or resource abuse.

Why it matters: Relying solely on read-only mode can leave systems vulnerable.

Expert Zone

1

Writable tmpfs mounts are stored in memory and disappear on container stop, which can be exploited if sensitive data is written there unintentionally.

2

Some applications expect to write to certain paths; careful volume or tmpfs planning is needed to avoid runtime errors in read-only containers.

3

Combining read-only filesystems with user namespaces and seccomp profiles greatly reduces attack surface beyond just file immutability.

When NOT to use

Avoid read-only filesystems for containers that must persist state internally or modify many files during runtime, such as databases or complex applications. Instead, use writable containers with managed volumes or stateful orchestration solutions.

Production Patterns

In production, read-only containers are often paired with immutable infrastructure practices, where containers are replaced rather than updated. They are used for stateless microservices, batch jobs, and security-sensitive workloads. Logs and temp data are redirected to external systems or writable mounts. Security teams combine this with runtime monitoring and access controls.

Connections

Immutable Infrastructure

Builds-on

Read-only filesystem containers are a practical implementation of immutable infrastructure principles, ensuring environments do not change after deployment.

Linux OverlayFS

Underlying technology

Understanding OverlayFS helps grasp how Docker layers work and why disabling the writable layer creates a read-only container.

Digital Rights Management (DRM)

Similar pattern

Both read-only containers and DRM restrict modification rights to protect content or systems, showing how access control concepts apply across fields.

Common Pitfalls

#1 Trying to write logs inside the root filesystem of a read-only container without writable mounts.

Wrong approach:

docker run --read-only alpine sh -c "echo 'log' >> /var/log/app.log"

Correct approach:

docker run --read-only -v logdata:/var/log alpine sh -c "echo 'log' >> /var/log/app.log"

Root cause:

Misunderstanding that the root filesystem is read-only and writable volumes are needed for file writes.

#2 Assuming --read-only disables all container changes including environment variables.

Wrong approach:

docker run --read-only alpine env VAR=changed

Correct approach:

docker run --read-only -e VAR=changed alpine env

Root cause:

Confusing filesystem immutability with process or environment immutability.

#3 Mounting sensitive writable volumes without proper access controls in a read-only container.

Wrong approach:

docker run --read-only -v /host/secret:/data alpine

Correct approach:

docker run --read-only -v /host/secret:/data:ro alpine

Root cause:

Not realizing writable mounts can bypass read-only filesystem protections if not carefully managed.

Key Takeaways

Read-only filesystem containers prevent file changes during runtime by disabling the writable layer.

They improve security and consistency but require writable volumes or tmpfs for logs and temp files.

The read-only option is set at container start, not in the image, allowing flexible use.

Read-only filesystems are one layer of defense and should be combined with other security measures.

Understanding Docker's layered filesystem and volume mounts is key to using read-only containers effectively.