Updated November 2026: Refreshed for Docker 29, Compose v5 and Kubernetes 1.37: added Compose read_only/tmpfs, memory-backed emptyDir with sizeLimit, a Pod Security Standards “restricted” example and a diagram; all Docker commands re-run against current nginx:alpine.

A read-only root filesystem is one of the cheapest ways to harden a container. If an attacker gets code execution inside it, they can’t drop binaries, patch config files or tamper with the application. Most applications still need to write somewhere (PID files, caches, temp files), so the pattern is always the same: make the root filesystem read-only and mount small, writable scratch areas exactly where the application needs them.

Read-only root filesystem with writable tmpfs or emptyDir mounts

I’ll walk through this with NGINX, first in Docker, then in Docker Compose and finally in Kubernetes.

Read-only filesystem in Docker: --read-only

docker run has a --read-only flag that mounts the container’s root filesystem read-only. A quick test with ubuntu:

BASH
docker run --rm --read-only ubuntu touch /hello
touch: cannot touch '/hello': Read-only file system

That’s fine for a container that never writes. NGINX, however, does:

BASH
docker run -d --name web -p 8080:80 --read-only nginx:alpine
docker logs web
TEXT
...
10-listen-on-ipv6-by-default.sh: info: can not modify /etc/nginx/conf.d/default.conf (read-only file system?)
/docker-entrypoint.sh: Configuration complete; ready for start up
[emerg] 1#1: mkdir() "/var/cache/nginx/client_temp" failed (30: Read-only file system)
nginx: [emerg] mkdir() "/var/cache/nginx/client_temp" failed (30: Read-only file system)

The info line about default.conf is harmless: the entrypoint just can’t add the IPv6 listen directive, and I don’t want runtime changes to the config anyway. The [emerg] line is the real problem. NGINX needs a writable /var/cache/nginx.

Writable paths with --tmpfs

A tmpfs mount is an in-memory filesystem that lives as long as the container. It isn’t persisted, and it isn’t shared with other containers. Exactly what we want for scratch data. Let’s add one for the cache directory:

BASH
docker rm -f web
docker run -d --name web -p 8080:80 --read-only \
  --tmpfs /var/cache/nginx \
  nginx:alpine
docker logs web
TEXT
...
[emerg] 1#1: open() "/run/nginx.pid" failed (30: Read-only file system)
nginx: [emerg] open() "/run/nginx.pid" failed (30: Read-only file system)

One step further. Now NGINX wants to write its PID file to /run (/var/run is a symlink to it on Alpine). Add a second tmpfs:

BASH
docker rm -f web
docker run -d --name web -p 8080:80 --read-only \
  --tmpfs /var/cache/nginx \
  --tmpfs /run \
  nginx:alpine
docker logs web
TEXT
...
[notice] 1#1: nginx/1.31.9
[notice] 1#1: start worker processes

NGINX is up, and the rest of the filesystem is still locked down:

BASH
curl -s localhost:8080 | grep title
<title>Welcome to nginx!</title>

docker exec web touch /etc/nginx/nginx.conf
touch: /etc/nginx/nginx.conf: Read-only file system

docker exec web touch /run/ok   # works

Docker mounts a tmpfs with rw,nosuid,nodev,noexec by default, so nothing written there can be executed. The size is unbounded unless you set it, which I recommend for anything that isn’t tiny: --tmpfs /var/cache/nginx:size=16m. If you need more options (mode, uid), the long form is --mount type=tmpfs,destination=/var/cache/nginx,tmpfs-size=16m.

Docker Compose: read_only and tmpfs

In Compose, the same setup is two keys on the service:

YAML
# compose.yaml
services:
  web:
    image: nginx:alpine
    read_only: true
    tmpfs:
      - /var/cache/nginx:size=16m
      - /run
    ports:
      - "8080:80"

docker compose up -d starts NGINX with a read-only root filesystem and two writable tmpfs mounts.

Kubernetes: securityContext.readOnlyRootFilesystem

In Kubernetes, you set readOnlyRootFilesystem: true in the container’s securityContext. It’s a per-container field, there is no pod-level equivalent. Instead of tmpfs mounts, you use emptyDir volumes for the writable paths. An emptyDir is created when the Pod is scheduled to a node and deleted with the Pod. By default it’s backed by the node’s disk; with medium: Memory it’s a tmpfs.

Here is the NGINX example from above as a Pod:

YAML
# pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: webserver
spec:
  containers:
    - name: webserver
      image: nginx:alpine
      securityContext:
        readOnlyRootFilesystem: true
      ports:
        - containerPort: 80
      volumeMounts:
        - name: nginx-cache
          mountPath: /var/cache/nginx
        - name: run
          mountPath: /run
  volumes:
    - name: nginx-cache
      emptyDir: {}
    - name: run
      emptyDir:
        medium: Memory
        sizeLimit: 1Mi
BASH
kubectl apply -f pod.yaml
kubectl port-forward pod/webserver 8080:80

Two things to keep in mind with medium: Memory: files in it count against the container’s memory limit, and they’re lost on a node reboot. Always set a sizeLimit so a runaway process can’t fill the node’s RAM. For caches that may grow, a disk-backed emptyDir (with a sizeLimit as well) is usually the better choice.

Read-only root filesystem and Pod Security Standards

PodSecurityPolicy, which used to be the way to enforce readOnlyRootFilesystem cluster-wide, was removed in Kubernetes 1.25. Its successor, Pod Security Admission, enforces the Pod Security Standards . Note that the restricted profile does not require readOnlyRootFilesystem. It requires a non-root user, no privilege escalation, dropped capabilities and a seccomp profile, and it allows emptyDir volumes. If you want read-only root filesystems everywhere, enforce them with a policy engine like Kyverno, OPA Gatekeeper or a ValidatingAdmissionPolicy.

The official nginx image runs as root and binds port 80, so it won’t pass restricted. The nginxinc/nginx-unprivileged image runs as UID 101, listens on 8080 and writes everything (PID file and temp paths) to /tmp. That means a single emptyDir is enough:

YAML
# deployment.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: web
  labels:
    pod-security.kubernetes.io/enforce: restricted
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: webserver
  namespace: web
spec:
  replicas: 1
  selector:
    matchLabels:
      app: webserver
  template:
    metadata:
      labels:
        app: webserver
    spec:
      securityContext:
        runAsNonRoot: true
        seccompProfile:
          type: RuntimeDefault
      containers:
        - name: webserver
          image: nginxinc/nginx-unprivileged:alpine
          ports:
            - containerPort: 8080
          securityContext:
            readOnlyRootFilesystem: true
            allowPrivilegeEscalation: false
            capabilities:
              drop: ["ALL"]
          resources:
            limits:
              memory: 128Mi
          volumeMounts:
            - name: tmp
              mountPath: /tmp
      volumes:
        - name: tmp
          emptyDir:
            medium: Memory
            sizeLimit: 32Mi

Without the /tmp volume, this container fails the same way as before (mkdir() "/tmp/proxy_temp" failed (30: Read-only file system)).

Finding the paths your app writes to

The fastest way I know is the one used above: start the container read-only, read the error, add a mount, repeat. For a more complete picture, run the container without --read-only, exercise it, and ask Docker what changed:

BASH
docker run -d --name probe nginx:alpine
docker diff probe
TEXT
C /run
A /run/nginx.pid
C /var/cache/nginx
A /var/cache/nginx/client_temp
...
C /etc/nginx/conf.d/default.conf

There they are: /run, /var/cache/nginx, and the default.conf the entrypoint patched. Every A (added) or C (changed) path outside your volumes is a candidate for a tmpfs or emptyDir. Keep that list as short as possible, and prefer pointing the application at a single directory like /tmp over mounting half the filesystem writable.

Conclusion

A read-only root filesystem is a one-line change in Docker (--read-only), Compose (read_only: true) and Kubernetes (readOnlyRootFilesystem: true). The work is in finding the few paths your application has to write to and mounting a tmpfs or emptyDir there. Once that’s done, you get a container that can’t be modified at runtime, and that’s worth it for every workload you ship.