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.

Practice

1. What does the --read-only flag do when starting a Docker container?

easy

A. Runs the container with root privileges.

B. Deletes all files inside the container before starting it.

C. Makes the container's filesystem read-only, preventing any changes inside it.

D. Allows the container to write to the host filesystem.

Solution

1. Step 1: Understand the --read-only flag purpose

   The --read-only flag makes the container's filesystem read-only, so no files can be changed or created inside the container.

2. Step 2: Compare other options

   Running with root privileges, deleting files, or allowing writes to the host filesystem are unrelated or incorrect behaviors for this flag.

3. Final Answer:

   Makes the container's filesystem read-only, preventing any changes inside it. -> Option C

4. Quick Check:

   --read-only = read-only filesystem [OK]

Hint: Remember: --read-only locks container files from changes [OK]

Common Mistakes:

• Thinking it deletes files instead of locking them
• Confusing with volume mounts
• Assuming it grants root access

2. Which of the following is the correct Docker command to start a container with a read-only filesystem?

easy

A. docker run --read-only alpine

B. docker run --readonly alpine

C. docker run -ro alpine

D. docker run --readwrite alpine

Solution

1. Step 1: Check the correct flag syntax

   The correct flag to make the filesystem read-only is --read-only with a hyphen.

2. Step 2: Validate options

   docker run --read-only alpine uses the correct flag --read-only. The short flag -ro doesn't exist, --readonly lacks the hyphen, and --readwrite is the opposite meaning.

3. Final Answer:

   docker run --read-only alpine -> Option A

4. Quick Check:

   Correct flag is --read-only [OK]

Hint: Use double dash and hyphen: --read-only [OK]

Common Mistakes:

• Using --readonly without hyphen
• Using short flags like -ro which don't exist
• Confusing with --readwrite

3. Consider this command:
docker run --read-only -v /data alpine sh -c "echo hello > /data/file.txt && cat /data/file.txt"
What will be the output?

medium

A. hello

B. Permission denied error

C. No such file or directory error

D. Empty output

Solution

1. Step 1: Understand --read-only with volume mount

   The container filesystem is read-only, but the /data directory is mounted as a volume, which is writable.

2. Step 2: Analyze the command behavior

   The command writes "hello" to /data/file.txt and then reads it back. Since /data is writable, this succeeds and outputs "hello".

3. Final Answer:

   hello -> Option A

4. Quick Check:

   Writable volume inside read-only container = writable [OK]

Hint: Writable volumes override read-only container filesystem [OK]

Common Mistakes:

• Assuming entire container is fully read-only including volumes
• Expecting permission denied on volume writes
• Confusing volume mount syntax

4. You run this command:
docker run --read-only alpine sh -c "touch /tmp/testfile"
But it fails with a permission error. What is the best fix?

medium

A. Remove the --read-only flag

B. Add a writable tmpfs mount for /tmp using --tmpfs /tmp

C. Run the container as root user

D. Use -v /tmp:/tmp to mount host /tmp

Solution

1. Step 1: Identify cause of permission error

   The container filesystem is read-only, so creating files in /tmp fails.

2. Step 2: Provide writable space with tmpfs

   Using --tmpfs /tmp mounts a writable temporary filesystem at /tmp, allowing file creation despite read-only root.

3. Final Answer:

   Add a writable tmpfs mount for /tmp using --tmpfs /tmp -> Option B

4. Quick Check:

   Writable tmpfs fixes write errors in read-only containers [OK]

Hint: Use --tmpfs to add writable temp folders in read-only containers [OK]

Common Mistakes:

• Removing --read-only loses security benefits
• Mounting host /tmp may cause permission issues
• Assuming root user can write despite read-only filesystem

5. You want to run a container with a read-only filesystem but allow writing only to /app/logs. Which command correctly achieves this?

hard

A. docker run --read-only alpine

B. docker run --read-only --tmpfs /app/logs alpine

C. docker run -v /host/logs:/app/logs alpine

D. docker run --read-only -v /host/logs:/app/logs alpine

Solution

1. Step 1: Understand read-only with writable folder

   The container filesystem is read-only, but mounting a host directory as a volume at /app/logs makes that folder writable.

2. Step 2: Evaluate options

   docker run --read-only -v /host/logs:/app/logs alpine uses --read-only plus a volume mount for writable logs. docker run --read-only --tmpfs /app/logs alpine uses tmpfs which is temporary and not persistent. docker run -v /host/logs:/app/logs alpine lacks --read-only. docker run --read-only alpine has no writable folder.

3. Final Answer:

   docker run --read-only -v /host/logs:/app/logs alpine -> Option D

4. Quick Check:

   Volume mount + --read-only = writable folder [OK]

Hint: Use volume mount with --read-only for writable folders [OK]

Common Mistakes:

• Using tmpfs when persistence is needed
• Forgetting --read-only flag
• Expecting writable without volume or tmpfs