Skip to content
Tutorials Center
My learning

Topics

Lesson 45 of 111 ยท Data and Volumes

Container Storage

Understand why data disappears when a container is removed, how the writable layer and copy-on-write work, and when to use volumes, bind mounts or tmpfs mounts.

Sooner or later every Docker beginner has the same experience: you start a container, create some data, remove the container, and the data is gone. It feels like a bug, but it is the design. A container is meant to be disposable, started from an image whenever you need one and thrown away when you do not. Anything that must outlive the container needs a different home.

This lesson explains where a container's files live while it runs, why they vanish, and the three places you can put data so that they do not: volumes, bind mounts and tmpfs mounts. It is the foundation for the rest of this chapter (Volumes, Bind Mounts, tmpfs and In-Memory Storage). Every session below was run on a real Docker Engine.

The writable layer

An image is a stack of read-only layers (see Layers and the Union Filesystem). When Docker creates a container, it does not copy the image. It adds one thin writable layer on top of the stack, and the container sees the whole thing as a single filesystem.

TEXT
        container A              container B
   +------------------+    +------------------+
   |  writable layer  |    |  writable layer  |   <- private, deleted with the container
   +------------------+    +------------------+
   |                                          |
   |      image layers (read-only, shared)    |   <- the same bytes for both containers
   |   [ app code ] [ packages ] [ base OS ]  |
   +------------------------------------------+

Everything the container writes lands in its own writable layer: new files, edited files, deleted files. Two containers started from the same image share all the image layers and have independent writable layers. Let us watch that happen:

CONSOLE
$ docker run -d --name box alpine:3.22 sh -c 'echo "hello" > /notes.txt; sleep 300'
$ docker exec box cat /notes.txt
hello
$ docker diff box
A /notes.txt

docker diff lists what the writable layer contains: A for added, C for changed, D for deleted. The file exists only there. Stop and start the same container and the file is still present, because stopping does not delete the writable layer:

CONSOLE
$ docker stop box && docker start box
$ docker exec box cat /notes.txt
hello

A second container started from the same image has never heard of the file:

CONSOLE
$ docker run --rm alpine:3.22 cat /notes.txt
cat: can't open '/notes.txt': No such file or directory

And when the container is removed, the writable layer goes with it. A replacement container starts from the pristine image:

CONSOLE
$ docker rm -f box
$ docker run -d --name box alpine:3.22 sleep 300
$ docker exec box ls /notes.txt
ls: /notes.txt: No such file or directory

That is exactly what happens when you upgrade a database container by removing the old one and starting a new one with a newer image: without something outside the container, all rows are gone. Remember the rule: the writable layer lives and dies with the container.

Copy-on-write

What if the container changes a file that comes from the image? The image layers are read-only, so Docker uses copy-on-write: the first time the container modifies a file, the whole file is copied up into the writable layer and the change is made there. Deleting a file does not remove it from the image; it records a "whiteout" marker in the writable layer that hides it. We edited, deleted and created things in a fresh Alpine container:

CONSOLE
$ docker exec box sh -c 'echo "extra" >> /etc/motd; rm /etc/profile; mkdir /newdir'
$ docker diff box
C /etc
C /etc/motd
D /etc/profile
A /newdir

/etc/motd was copied up and modified (C), /etc/profile is hidden (D) though its bytes remain in the image, and /newdir is new (A). The directory /etc is marked changed because its contents changed. Writing a large file shows up in the container's size:

CONSOLE
$ docker ps -s --filter name=box --format 'table {{.Names}}\t{{.Size}}'
NAMES     SIZE
box       24.6kB (virtual 9.02MB)
$ docker exec box dd if=/dev/zero of=/big bs=1M count=20
$ docker ps -s --filter name=box --format 'table {{.Names}}\t{{.Size}}'
NAMES     SIZE
box       21MB (virtual 30MB)

The first number is the size of the writable layer; "virtual" adds the read-only image below it. A container that writes a lot of data into its own layer grows without bound and cannot share it with others.

Why the writable layer is the wrong place for important data

  • It is not durable. Removing the container (including docker compose down, or an orchestrator replacing it) deletes the data.
  • It is tied to one container. You cannot easily share it with another container, back it up, or move it to a new host.
  • It is slower. Writes go through the union filesystem driver (overlay2 or the containerd snapshotter), which adds overhead compared with a direct mount, especially for many small writes such as database files.
  • It cannot be inspected from outside as simply as a directory on your machine.

Docker's answer is to mount something into the container at a path of your choice. Whatever is mounted there is not part of the writable layer: the container reads and writes it directly, and it survives the container.

Three kinds of mount

TEXT
 host machine
 +-------------------------------------------------------------+
 |  Docker's own storage area        any folder you choose     |  RAM
 |  (managed by Docker)              (/home/you/project)       |
 |     [ volume ]                       [ bind mount ]         | [ tmpfs ]
 +--------|-----------------------------------|----------------------|--+
          |                                   |                      |
      +---v-----------------------------------v----------------------v---+
      |                          container                               |
      |     /var/lib/db                   /app/src             /scratch  |
      +------------------------------------------------------------------+
Volume Bind mount tmpfs mount
Lives in Docker's storage area, managed by Docker Any path on the host that you name Host memory (RAM)
Created by Docker (docker volume create or on first use) You, beforehand Docker, empty
Survives container removal Yes Yes (it is your folder) No, not even a restart
Typical use Databases, uploads, anything the app owns Source code in development, config files Scratch data, secrets in memory
Works the same on every OS Yes Paths and permissions differ Linux containers only
Pre-filled from the image Yes, when new and empty No (the host folder hides the image's files) No

All three are attached with -v / --volume (short) or --mount (explicit, key=value) on docker run, and with volumes: and tmpfs: in Compose. Here is one container using all of them at once:

CONSOLE
$ docker run -d --name mounts \
    -v appdata:/data \
    --mount type=bind,src="$PWD/site",dst=/site,readonly \
    --tmpfs /scratch:size=16m \
    alpine:3.22 sleep 300

-v appdata:/data has a name before the colon, so it is a named volume. The --mount type=bind form spells everything out and, with readonly, makes the container unable to modify the host folder. --tmpfs creates the in-memory mount with a size cap. Ask Docker what it set up:

CONSOLE
$ docker inspect -f '{{range .Mounts}}{{.Type}}|{{.Name}}|{{.Destination}}|rw={{.RW}}{{println}}{{end}}' mounts
volume|appdata|/data|rw=true
bind||/site|rw=false

$ docker inspect -f '{{json .HostConfig.Tmpfs}}' mounts
{"/scratch":"size=16m"}

(docker inspect lists tmpfs mounts separately, under HostConfig.Tmpfs.) Inside the container each one looks like an ordinary directory, but they are different filesystems:

CONSOLE
$ docker exec mounts sh -c 'echo v > /data/v.txt; echo t > /scratch/t.txt; cat /site/index.html; echo x > /site/new.txt'
<h1>from the host</h1>
sh: can't create /site/new.txt: Read-only file system
$ docker exec mounts sh -c 'mount | grep -E " /data | /scratch "'
/dev/sdd on /data type ext4 (rw,relatime)
tmpfs on /scratch type tmpfs (rw,nosuid,nodev,noexec,relatime,size=16384k)
$ docker exec mounts df -h /data /scratch
Filesystem                Size      Used Available Use% Mounted on
/dev/sdd               1006.9G     43.0G    912.6G   5% /data
tmpfs                     16.0M      4.0K     16.0M   0% /scratch

The device names and sizes depend on your machine (here, Docker Desktop's virtual disk). What matters: /data is a real disk filesystem, /scratch is a 16 MB tmpfs, and the bind mount refused the write because we made it read-only. Now restart the container and see what survives:

CONSOLE
$ docker stop mounts && docker start mounts
$ docker exec mounts sh -c 'ls /data /scratch'
/data:
v.txt

/scratch:

The volume kept v.txt; the tmpfs came back empty. Finally remove the container altogether and look at the volume from a brand new one:

CONSOLE
$ docker rm -f mounts
$ docker run --rm -v appdata:/data alpine:3.22 cat /data/v.txt
v
$ docker volume inspect appdata --format '{{.Name}} {{.Driver}} {{.Scope}}'
appdata local local

The data outlived the container that created it. This is the whole point of volumes.

Choosing between them

Ask what the data is and who owns it.

  • The application owns it and it must persist (database files, uploaded images, a Redis snapshot): use a named volume. Docker manages the location, it behaves identically on Linux, macOS and Windows, it performs well, and you can back it up with a helper container (Backup and Restore).
  • You own it and want to see or edit it on the host (source code under development, a config file you tweak, build output you want to open in your editor): use a bind mount. Be aware of host paths and file ownership issues (Users and Permissions).
  • It is temporary and perhaps sensitive (scratch space, caches, a decrypted secret you do not want on disk): use tmpfs. It is fast and it can never be written to disk. It counts against the container's memory.
  • It is a one-time output of a job: print to stdout and let logs or the orchestrator handle it, or write to a volume or object storage; never to the writable layer.

A common pattern combines them: the application image contains the code (read-only layers), a named volume holds the data, a bind mount supplies configuration in development, and a tmpfs gives a place for temporary files so the root filesystem can be read-only.

Make the container's own filesystem disposable. If you could delete and recreate any container at any moment without losing anything, you have storage right. Test it: docker rm -f the container and start a new one.

The VOLUME instruction and anonymous volumes

An image author can declare a path in the Dockerfile with VOLUME /var/lib/postgresql/data. If you start a container from that image without mounting something there yourself, Docker creates an anonymous volume (a volume with a random name) to hold it, so even careless runs do not lose data to the writable layer. The catch is that anonymous volumes are hard to recognize, and are not removed by docker rm unless you add -v. They accumulate (see Cleaning Up). When you run such an image, give the path a name: -v mydb:/var/lib/postgresql/data.

Files that the image already contains at the VOLUME path are copied into a new volume the first time it is used, so a volume can come pre-filled (we built an image that wrote one file before and one after its VOLUME /vdata line; with BuildKit both ended up in the image, and a container showed both). Declare a VOLUME only for directories that really hold data, and see WORKDIR, USER, EXPOSE and LABEL for the other metadata instructions.

Rules of thumb

  1. Treat the container filesystem as read-only, even if you do not enforce it.
  2. Persist data with a volume, and give the volume a real name.
  3. Use bind mounts for development convenience, not as a production storage design.
  4. Use tmpfs for temporary or sensitive files.
  5. Back up volumes. A volume protects against container removal, not against disk failure, mistakes or docker volume rm.
  6. Know where each path your application writes goes. If you do not, run docker diff on a container that has been running for a while: everything listed there is in the writable layer.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A container writes /notes.txt, is stopped and started again, and the file is still there. After docker rm and a new docker run of the same image, the file is gone. Why?

    The writable layer belongs to the container. A stop/start keeps it; docker rm deletes it. A new container gets a fresh, empty writable layer on top of the unchanged image.
  2. 2. What does the C /etc/motd line in docker diff mean?

    C marks a changed file. Because image layers are read-only, Docker copies the file into the writable layer on first modification (copy-on-write). A is added and D is deleted.
  3. 3. Which storage type is the best default for a database's data directory in production?

    Named volumes are managed by Docker, survive container removal, perform well and behave the same on every platform. The writable layer and tmpfs are not durable, and a read-only mount could not be written to.
  4. 4. After docker stop and docker start of a container with a volume at /data and a tmpfs at /scratch, what do you find?

    A tmpfs lives in memory and is discarded when the container stops. The volume lives on disk, outside the container, and keeps its contents.
  5. 5. Why should you give the path of an image's VOLUME a named volume at run time?

    An anonymous volume is created automatically but has a 64-character random name and is not removed by a plain docker rm. A named volume is easy to identify, back up and reuse.

Summary

  • A container sees the image's read-only layers plus one private writable layer; writes go there, using copy-on-write for files that come from the image.
  • The writable layer survives stop/start but is deleted with the container, so never keep important data in it. docker diff shows what is in it.
  • Volumes live in Docker's storage area and are the default choice for persistent application data.
  • Bind mounts map a host folder into the container and suit development; they depend on host paths and permissions.
  • tmpfs mounts live in memory and vanish when the container stops; use them for scratch data and sensitive temporary files.
  • Declare data directories with named volumes (and VOLUME in Dockerfiles carefully); anonymous volumes accumulate.
  • Test your design by deleting and recreating the container: nothing important should be lost.

Next: Volumes