Storage & Volumes

The four mount types

┌─── CONTAINER ─────────────────────────────────────────────┐
│  /app/data  ←── volume (mydata)     [Docker-managed]      │
│  /src       ←── bind mount ./src      [host path]          │
│  /run/secrets ← tmpfs               [RAM, no disk]        │
│  /var/run/docker.sock ← bind mount  [named socket/pipe]   │
├───────────────────────────────────────────────────────────┤
│  Writable container layer (upperdir) — ephemeral CoW      │
├───────────────────────────────────────────────────────────┤
│  Read-only image layers (lowerdir)                        │
└───────────────────────────────────────────────────────────┘

Volumes — Docker-managed persistence

Volumes are the recommended default for persistent application data. Docker creates and tracks them; you reference them by name. They bypass the container's OverlayFS upperdir, so writes do not trigger copy-on-write penalties from image layers. Multiple containers can mount the same volume read-write or read-only.

Bind mounts — host path coupling

Bind mounts map a specific host path into the container. Docker does not manage the data—you do. The container sees the host inode directly. Powerful for development (edit locally, run in container) but couples deployment to host filesystem layout and UID/GID mapping.

tmpfs — memory-backed, ephemeral

tmpfs mounts store data in RAM (and swap). Nothing hits disk—ideal for credentials that must not persist, or high-churn temp files you do not want polluting the container layer. Size is bounded by --tmpfs size flags and available memory.

Named pipes and sockets

Not traditional storage, but a mount type worth knowing: binding a Unix socket or FIFO lets containers talk to host services. The classic example is mounting /var/run/docker.sock so a CI agent can spawn sibling containers—a powerful and dangerous pattern covered in security guides.

# Volume (named, managed)
docker run -d --name db -v pgdata:/var/lib/postgresql/data postgres:16

# Bind mount (host path)
docker run --rm -v $(pwd)/src:/app/src:ro node:20 npm test

# tmpfs (RAM only)
docker run --rm --tmpfs /run/secrets:rw,noexec,nosuid,size=64m myapp

# Named socket (IPC)
docker run -v /var/run/docker.sock:/var/run/docker.sock docker:cli

Volume lifecycle commands

$ docker volume create --driver local --opt type=nfs \
  --opt o=addr=10.0.1.50,rw --opt device=:/exports/pgdata pgdata_nfs
pgdata_nfs

$ docker volume inspect pgdata_nfs --format '{{.Mountpoint}}'
/var/lib/docker/volumes/pgdata_nfs/_data

$ docker run -d --name postgres -v pgdata_nfs:/var/lib/postgresql/data postgres:16
a3f8c2d1e9b0...

$ docker volume ls --filter name=pgdata
DRIVER    VOLUME NAME
local     pgdata_nfs

Volume drivers

The default local driver stores data under Docker's data root. Plugin drivers extend storage to network filesystems and cloud block stores—critical for multi-host Swarm and legacy Docker EE deployments. Kubernetes uses its own CSI drivers instead, but the concepts transfer.

-v vs --mount syntax

Both attach storage, but --mount is explicit and recommended for production scripts. The shorthand -v is easy to misread—host vs container path order trips people up, and it silently creates host directories for bind mounts.

Anonymous volumes

When you specify only a container path—-v /var/lib/mysql with no name—Docker creates an anonymous volume with a random ID. Data survives container removal unless you pass -v on docker rm (v1) or use docker rm -v. These accumulate as orphaned disk usage. Official database images use anonymous volumes in their Dockerfile VOLUME instruction—always replace with a named volume in production.

Permissions and ownership

Volume data is written by the container process UID/GID. If the image runs as UID 999 (postgres) but the host directory is owned by root, you get permission denied. Fixes:

• docker run --user to match host ownership
• Init container or entrypoint script that chowns the mount (common in dev)
• COPY --chown=app:app in Dockerfile so the runtime user owns expected paths
• Named volume (Docker initializes with root; database entrypoints fix permissions on first start)

Backup with tar

The canonical volume backup pattern: mount the volume into a throwaway container and stream a tar archive to stdout. Restore is the reverse—extract tar into a fresh volume. Works for any volume driver whose data is accessible locally.

# Backup: stream volume to host tar file
docker run --rm \
  -v pgdata:/source:ro \
  -v $(pwd):/backup \
  alpine tar czf /backup/pgdata-$(date +%Y%m%d).tar.gz -C /source .

# Restore: extract tar into a new volume
docker volume create pgdata_restored
docker run --rm \
  -v pgdata_restored:/target \
  -v $(pwd):/backup \
  alpine sh -c "cd /target && tar xzf /backup/pgdata-20260605.tar.gz"

# Verify restored volume
docker run --rm -v pgdata_restored:/data alpine ls -la /data

Dev hot reload pattern

The standard local development loop: bind-mount source code, keep dependencies in the image layer or a named volume. Spring Boot DevTools, Node nodemon, and Vite HMR all depend on the host writing files the container process watches.

# Spring Boot dev: mount source, cache Maven deps in named volume
docker run --rm -p 8080:8080 \
  -v $(pwd)/src:/app/src \
  -v maven_cache:/root/.m2 \
  -w /app \
  maven:3.9-eclipse-temurin-21 mvn spring-boot:run

# Node dev: mount everything except node_modules
docker run --rm -p 3000:3000 \
  -v $(pwd):/app \
  -v /app/node_modules \
  -w /app node:20 npm run dev

The anonymous volume trick -v /app/node_modules masks the bind mount for that path—container-installed node_modules wins over the (empty or macOS-incompatible) host directory.

Read-only bind mounts (:ro)

Mount configuration and secrets read-only so a compromised container cannot modify them. Compose: ./config.yml:/app/config.yml:ro. Kubernetes equivalent is readOnly: true on volume mounts. Read-only does not prevent reading— sensitive files still need proper permissions and tmpfs for runtime secrets.

Permissions and UID mapping

Risks of bind mounts

• Host path exposure — mounting / or /etc gives the container full host read (or write) access
• Non-portable deploys — production paths differ; bind mounts break across machines
• Accidental deletion — rm -rf inside the container can destroy host data
• Docker creates missing dirs — -v /nonexistent:/data creates /nonexistent as root on the host

When to use bind mounts

How the writable layer works

Image layers form the lowerdir stack. Docker creates a unique upperdir per container—all runtime writes land here. The merged view is the container root filesystem. When the container is removed, upperdir is deleted. No backup, no recovery.

  READ path:  upperdir → lowerN → … → lower0  (first hit wins)
  WRITE path: file in lower? → COPY to upperdir (CoW) → write
              new file?      → create directly in upperdir

  ┌──────── upperdir (container writable layer) ────────┐
  │  /app/logs/app.log  ← created here at runtime        │
  │  /etc/hosts         ← copied from lower, then edited │
  ├──────── lowerdir (image layers, read-only) ─────────┤
  │  Layer 3: RUN npm run build                          │
  │  Layer 2: COPY package.json                          │
  │  Layer 1: FROM node:20-alpine                        │
  └──────────────────────────────────────────────────────┘
           merged → container sees unified /

Copy-on-write cost

CoW triggers when a container modifies a file that exists in a lower layer. Docker copies the entire file to upperdir before applying the change—even for a one-byte edit. High-churn workloads (database page writes, log rotation, package managers writing to /usr) amplify this cost. Reads are fast; first-writes are not.

Never run databases in the container layer

SQLite, PostgreSQL, MySQL, Redis persistence—all belong on volumes. Database engines mmap files and issue small random writes. On the container layer this means constant CoW copies, no crash-safe guarantees across container recreation, and data loss on docker rm. This is not theoretical—it is the #1 "my database disappeared" incident.

$ docker run -d --name web nginx:alpine
f4a2b8c1d3e7...

$ docker exec web sh -c 'echo custom > /usr/share/nginx/html/test.html'

$ docker diff web
C /usr
C /usr/share
C /usr/share/nginx
C /usr/share/nginx/html
A /usr/share/nginx/html/test.html

$ docker inspect --format '{{.GraphDriver.Data.UpperDir}}' web
/var/lib/docker/overlay2/a3f8…/diff

Understanding docker diff

docker diff <container> lists changes in the writable layer relative to the image:

• A — Added file or directory
• C — Changed (modified metadata or CoW'd content)
• D — Deleted (whiteout over lower-layer file)

Use it to debug "why is my container using 2 GB of disk?"—often log files, package caches, or database files written to the wrong path. Pair with docker system df -v for per-container writable layer size.

OverlayFS read vs write characteristics

Reads from image layers are served from the page cache like normal files—excellent for read-heavy workloads (serving static assets from the image). Writes to the container layer incur CoW overhead. Volume writes skip OverlayFS entirely—they hit the volume driver backing store (local ext4/xfs, NFS, cloud block) with native filesystem performance.

flowchart TB
  subgraph reads["Read performance"]
    IMG[Image layer read] --> FAST[Fast — page cache]
    VOL_R[Volume read] --> FAST2[Fast — native FS]
    BIND_R[Bind mount read] --> VAR[Variable — host FS + sync layer]
  end
  subgraph writes["Write performance"]
    UPPER[Container layer write] --> COW[CoW penalty on first write]
    VOL_W[Volume write] --> NATIVE[Native FS — best for DB]
    BIND_W[Bind mount write] --> DESKTOP[Docker Desktop: FUSE/gRPC tax]
  end

Volume vs bind mount on Linux

On bare-metal or VM Linux hosts, volume and bind performance is comparable—both avoid CoW. Choose based on operability, not raw IOPS.

Docker Desktop: macOS and Windows FUSE slowness

Docker Desktop runs containers inside a Linux VM. Bind mounts cross a filesystem synchronization boundary (VirtioFS, gRPC FUSE, or osxfs depending on version). File-heavy operations— npm install, mvn compile, webpack watchers— can be 5–10× slower than on native Linux.

• Store node_modules, .m2, .gradle in named volumes, not bind mounts
• Enable VirtioFS (Docker Desktop settings) for improved macOS bind performance
• Use :delegated or :cached mount consistency flags on older Desktop versions
• Consider devcontainers with source inside the VM volume, synced selectively

Databases always use volumes

Regardless of platform, stateful data stores belong on volumes—not bind mounts, not the container layer:

• Crash consistency — volume data survives container restart and recreation
• I/O path — no CoW, no cross-VM sync on Desktop when volume lives in the Linux VM
• Backup — stable name for automation (pgdata, redis_data)
• Upgrade path — swap container image, reattach same volume

# Compose: production-shaped storage layout
services:
  app:
    image: myapp:1.0
    volumes:
      - app_logs:/var/log/myapp      # named volume — logs
    # NO bind mount of source in prod

  postgres:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data  # named volume — always
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_pass
    secrets:
      - db_pass

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    command: redis-server --appendonly yes

volumes:
  pgdata:
  redis_data:
  app_logs: