The Writable Layer: Where a Container's Writes Go

Every container has a writable layer: a thin, private area stacked on top of the image's read-only layers (the sets of files, one per build step, that make up the image the container was started from), where everything the container writes ends up. It is created when the container is created and deleted when the container is removed, so it decides which of a container's files survive.

Picture an application that saves uploaded files to /uploads inside its container. The program sees an ordinary directory and writes to it without complaint. Nothing about that directory tells the program, or you, that every upload will vanish when the container is removed.

Reads and writes work differently. When the program reads a file, Docker looks down through the layers and returns the first copy it finds, usually one from the image. When the program writes, the write stops at the top layer: a new file is created there, and a file from the image is first copied up and then changed there. The image's layers never change, however many containers use them.

The writable layer is part of the container. It is not a cache Docker keeps for you, and it is not a disk you can attach to another container. It lasts exactly as long as the container does: stopping the container keeps it, and removing the container deletes it. What stopping does lose is the program's memory: anything held only in memory is gone, while the files it wrote stay in the layer.

So anything you want to keep, such as uploads, a database or logs you will need later, has to be written somewhere that is not the container. That is what mounts are for: they connect a directory inside the container to storage that outlives it.