The Ephemeral Container Filesystem
A tester adds twenty notes to quicknotes, which saves them in /app/notes.db inside its container. You ship a new version: build, remove the old container, run the new one. The twenty notes are gone. Nothing crashed; this is exactly how containers are designed to behave.
The rule
The writable layer dies with the container, not with a stop.
Recall the layers: the image is read-only, and each container gets its own thin writable layer on top. Every file a container creates or changes lands there. That layer's life is tied to the container, not to the process inside it:
| Action | Writable layer |
|---|---|
docker stop then docker start |
kept |
docker restart, or a crash with a restart policy |
kept |
docker rm |
deleted |
| New container from the same image | starts empty |
So data in the writable layer is ephemeral: safe across stops, lost on replacement. And in Docker, replacement is the normal way to change anything. Upgrading, changing a setting or recovering from a broken state all mean "remove and run a new container".
docker run -d --name notes -p 8080:5000 quicknotes:1.0
# ... notes are added ...
docker rm -f notes
docker run -d --name notes -p 8080:5000 quicknotes:1.0
# a fresh writable layer: the notes are goneYou can see what a container has changed compared with its image:
docker diff notesIt lists files Added, Changed or Deleted in the writable layer. Seeing your data file there is a warning sign.
The writable layer is also the wrong place for heavy writing: going through the union filesystem is slower than writing to a volume, and its size is hard to manage.
The shortcut
For every file an app writes, ask "Would I cry if the container were replaced?" If yes, it must live outside the writable layer. Temporary files and caches can stay; data cannot.
/app/notes.db
The users' notes. Losing them on replacement is unacceptable. Must move outside the container.
Drills
Answer fast — trust the rule.
A container is stopped with docker stop and started again. What happened to files it wrote?
You remove the quicknotes container and run a new one from the same image. What does the new one see at /app/notes.db?
Which command lists files a container has added, changed or deleted compared with its image?
Which file is safe to leave in the container's writable layer?
Remember
- The writable layer dies with the container, not with a stop.
- Shortcut: "would I cry if the container were replaced?" Yes → store it outside.
- Trap: in Docker, replacing the container is the normal upgrade, so ephemeral data is lost routinely.