Docker Impl Storage

docker-impl-storage

Quick Reference

Storage Types

Critical Warnings

NEVER use anonymous volumes for database data -- data is lost when the container is removed with --rm. ALWAYS use named volumes for any data that must survive container recreation.

NEVER use -v syntax with volume drivers or driver options -- -v does not support them. ALWAYS use --mount when configuring volume drivers, NFS, or CIFS mounts.

NEVER run docker system prune -a --volumes on production systems without first checking docker volume ls -- this removes ALL unused volumes including database data.

NEVER mount /var/lib/docker/ as a bind mount inside a container -- this causes filesystem handle conflicts and Unable to remove filesystem errors.

ALWAYS use --mount syntax for production workloads and documentation -- it is explicit, self-documenting, and supports all mount options.

ALWAYS verify mount destination paths match the application's data directory -- mounting to the wrong path silently obscures existing container data.

Mount Type Decision Tree

Need to persist data?
├── NO → tmpfs mount (RAM-only, fastest, lost on stop)
│       docker run --mount type=tmpfs,dst=/tmp,tmpfs-size=64m IMAGE
│
└── YES → Need Docker to manage the storage?
    ├── YES → Named volume (portable, backupable, driver support)
    │       docker run --mount type=volume,src=mydata,dst=/data IMAGE
    │
    └── NO → Need host filesystem access?
        ├── YES → Bind mount (direct host path access)
        │       docker run --mount type=bind,src=/host/path,dst=/app IMAGE
        │
        └── NO → Named volume (default choice for persistence)

When to Use Each Type

--mount vs -v Syntax Comparison

--mount Syntax (Preferred)

Key-value pairs, explicit and self-documenting:

# Named volume
docker run --mount type=volume,src=mydata,dst=/data nginx

# Bind mount
docker run --mount type=bind,src=/host/path,dst=/container/path nginx

# tmpfs
docker run --mount type=tmpfs,dst=/tmp,tmpfs-size=64m nginx

# Read-only volume
docker run --mount source=data,destination=/data,readonly nginx

# Volume with subdirectory
docker run --mount src=logs,dst=/var/log/app1,volume-subpath=app1 app1

-v Syntax (Quick Development Only)

Three colon-separated fields: [name:]container-path[:options]

docker run -v mydata:/data nginx          # Named volume
docker run -v /host/path:/app nginx       # Bind mount
docker run -v mydata:/data:ro nginx       # Read-only

Key Differences

--mount Option Reference

Volume Lifecycle

Auto-Population Behavior

When mounting an empty named volume to a container directory that has existing files, Docker copies those files into the volume:

# Nginx HTML files get copied into nginx-vol on first mount
docker run -d --mount source=nginx-vol,destination=/usr/share/nginx/html nginx

NEVER rely on auto-population for production data -- it only happens once when the volume is empty. Use explicit initialization instead.

Named vs Anonymous Volumes

Simultaneous Mounting

Multiple containers can mount the same volume simultaneously. ALWAYS use read-only mounts for consumers that do not need write access:

# Writer container
docker run --mount source=shared,dst=/data mywriter

# Reader container (read-only)
docker run --mount source=shared,dst=/data,readonly myreader

Volume Drivers

Local Driver (Default)

Stores data on the host filesystem. Supports NFS, CIFS, and block devices via options.

NFS Volumes

# NFSv3
docker volume create --driver local \
  --opt type=nfs \
  --opt device=:/var/docker-nfs \
  --opt o=addr=10.0.0.10 \
  nfs-vol

# NFSv4
docker volume create --driver local \
  --opt type=nfs \
  --opt device=:/var/docker-nfs \
  --opt "o=addr=10.0.0.10,rw,nfsvers=4,async" \
  nfs-vol

CIFS/SMB Volumes

docker volume create --driver local \
  --opt type=cifs \
  --opt device=//server.example.com/backup \
  --opt o=addr=server.example.com,username=user,password=pass,file_mode=0777,dir_mode=0777 \
  --name cifs-vol

The addr option is REQUIRED when using a hostname instead of an IP address.

Third-Party Volume Drivers

# Install plugin
docker plugin install --grant-all-permissions rclone/docker-volume-rclone

# Create volume with plugin -- MUST use --mount syntax
docker run --mount type=volume,volume-driver=rclone,src=remote-vol,target=/app nginx

Database Persistence Patterns

PostgreSQL

docker run -d --name postgres \
  --mount source=pgdata,target=/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=secret \
  postgres:16

MySQL

docker run -d --name mysql \
  --mount source=mysqldata,target=/var/lib/mysql \
  -e MYSQL_ROOT_PASSWORD=secret \
  mysql:8

MongoDB

docker run -d --name mongo \
  --mount source=mongodata,target=/data/db \
  mongo:7

ALWAYS use named volumes for database containers. See references/examples.md for Compose patterns and backup procedures.

Storage Cleanup Strategy

# 1. Assess current usage FIRST
docker system df -v

# 2. List dangling volumes (not attached to any container)
docker volume ls -f dangling=true

# 3. Remove specific unused volumes
docker volume rm VOLUME_NAME

# 4. Remove ALL unused anonymous volumes
docker volume prune -f

# 5. Targeted prune (exclude labeled volumes)
docker volume prune --filter "label!=keep"

# 6. Full system cleanup (DANGEROUS on production)
docker system prune -a --volumes -f

ALWAYS run docker system df before pruning to understand what consumes space. NEVER run docker volume prune on production without verifying which volumes are unused.

Compose Volume Integration

services:
  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:                    # Named volume (managed by Compose)

See references/examples.md for NFS volumes, external volumes, and multi-service patterns in Compose.

Reference Links

• references/mount-types.md -- Complete comparison of volumes, bind mounts, and tmpfs with all options
• references/examples.md -- Database persistence, backup/restore, NFS volumes, Compose volume patterns
• references/anti-patterns.md -- Common storage mistakes and how to avoid them

Official Sources

• https://docs.docker.com/engine/storage/
• https://docs.docker.com/engine/storage/volumes/
• https://docs.docker.com/reference/cli/docker/volume/
• https://docs.docker.com/compose/how-tos/volumes/