Read-only filesystem containers in Docker - Commands & Configuration

Introduction

Sometimes you want to make sure a container cannot change its files to keep it safe and stable. Using a read-only filesystem means the container can only read files but cannot write or change them. This helps prevent accidental or harmful changes inside the container.

When running a container that only needs to read data and should not modify it, like a web server serving static files.

When you want to improve security by stopping attackers from changing files if they get access to the container.

When you want to make sure your container behaves the same every time by preventing file changes.

When running containers in production where stability and immutability are important.

When debugging or testing to ensure no files are accidentally changed during the container run.

Commands

This command runs a temporary container from the busybox image with its filesystem set to read-only. It lists the root directory to show the container is running and can read files.

Terminal

docker run --rm --read-only busybox ls /

Expected Output

bin

etc

proc

sys

usr

→

--read-only - Makes the container's filesystem read-only, preventing any file changes.

→

--rm - Automatically removes the container after it exits to keep the system clean.

This tries to create a new file inside the read-only container. It will fail because the filesystem does not allow writing.

Terminal

docker run --rm --read-only busybox touch /testfile

Expected Output

touch: /testfile: Read-only file system

→

--read-only - Prevents writing to the container filesystem.

→

--rm - Removes the container after it stops.

This runs a container with a read-only root filesystem but mounts a writable host directory at /data. It creates a file inside the mounted directory and lists it to show writing is allowed there.

Terminal

docker run --rm --read-only -v /tmp/data:/data busybox sh -c "touch /data/newfile && ls /data"

Expected Output

newfile

→

--read-only - Makes the container root filesystem read-only.

→

-v - Mounts a host directory to allow writing in that specific path.

→

--rm - Removes the container after it exits.

Key Concept

If you remember nothing else from this pattern, remember: the --read-only flag locks the container's filesystem to prevent any changes, improving security and stability.

Common Mistakes

Trying to write files inside the container without mounting a writable volume.

The container filesystem is read-only, so write operations fail with errors.

Mount a writable volume using -v to allow writing in specific directories.

Not using --rm flag during testing and leaving stopped containers on the system.

This clutters the system with unused containers and wastes disk space.

Always use --rm for temporary containers to clean up automatically.

Summary

Use the --read-only flag to make the container filesystem read-only and prevent file changes.

Write operations inside a read-only container fail unless you mount a writable volume.

Use -v to mount writable directories when you need to allow specific file changes.