DEV Community

Harry Douglas
Harry Douglas

Posted on

OverlayFS — The Magic Behind Docker

#docker #linux

Docker’s efficiency comes from a Linux kernel feature called OverlayFS. It allows multiple directories (called layers) to be combined into a single merged view. This is how Docker can reuse common image layers (Ubuntu, Alpine, etc.) across many containers, while giving each container its own writable layer.

In this tutorial, we’ll recreate Docker’s storage trick with a few simple commands.

🔹 Step 1: Setup directories

Create a playground with 4 directories:

mkdir overlayfs
cd overlayfs
mkdir -p lower upper work merged
Enter fullscreen mode Exit fullscreen mode
  • lower/ → base read-only layer (like Docker image layers)
  • upper/ → writable layer (container changes go here)
  • work/ → internal work area (needed by OverlayFS)
  • merged/ → final view (what the container “sees”)

🔹 Step 2: Add a file in the lower layer 

echo "hello from lower" > lower/file1.txt
Enter fullscreen mode Exit fullscreen mode

Check:

ls lower
# file1.txt
Enter fullscreen mode Exit fullscreen mode

🔹 Step 3: Mount OverlayFS

Now mount the union filesystem:

sudo mount -t overlay overlay \
  -o lowerdir=./lower,upperdir=./upper,workdir=./work \
  ./merged
Enter fullscreen mode Exit fullscreen mode

Check the merged view:

ls merged
# file1.txt
cat merged/file1.txt
# hello from lower
Enter fullscreen mode Exit fullscreen mode

🔹 Step 4: Create a new file in the merged layer 

echo "hello from upper" > merged/file2.txt
Enter fullscreen mode Exit fullscreen mode

Now inspect:

ls lower    # still file1.txt
ls upper    # now has file2.txt
ls merged   # file1.txt + file2.txt
Enter fullscreen mode Exit fullscreen mode

👉 New files go to upper.

🔹 Step 5: Modify an existing file (Copy-on-Write) 

echo "changed in merged" > merged/file1.txt
Enter fullscreen mode Exit fullscreen mode

Inspect again:

cat lower/file1.txt   # still "hello from lower"
cat upper/file1.txt   # now "changed in merged"
Enter fullscreen mode Exit fullscreen mode

👉 The file was copied from lower to upper, then modified = copy-on-write.

🔹 Step 6: Delete a file 

rm merged/file1.txt
Enter fullscreen mode Exit fullscreen mode

Now:

ls merged   # only file2.txt
ls lower    # still has file1.txt
ls upper    # contains a "whiteout" marker
Enter fullscreen mode Exit fullscreen mode

👉 OverlayFS hides lower’s file1.txt using a special whiteout file.

🔹 Step 7: Unmount

When done, unmount:

sudo umount merged
Enter fullscreen mode Exit fullscreen mode

The merged view disappears, but the lower/upper directories still contain their raw files.

🔹 Key Takeaways

  • Lowerdir = base image layers (read-only)
  • Upperdir = writable container layer
  • Workdir = bookkeeping area for OverlayFS
  • Merged = what the container sees
  • Copy-on-Write = changes to lower files go into upper
  • Whiteouts = hide deleted files from lower

✅ And that’s it — you’ve just reproduced Docker’s storage mechanism by hand!

Top comments (0)