mergerfs docker setup - merge multiple drives into one mount for containers
when you have multiple hard drives and want Docker containers to treat them as one filesystem, mergerfs is the cleanest solution. here's how to set up mergerfs with Docker volumes on a Linux media server.
the problem with multiple drives and docker
the media server runs on a box with three data drives - two 4TB NAS drives and a 7TB drive, around 14.5TB total. choosing the right hard drive for a media server matters - NAS-rated drives like the Seagate IronWolf are built for always-on workloads and handle the constant read/write from streaming and downloading without overheating. apps like Jellyfin, Sonarr, and Radarr need to see one unified media library, not three separate mount points.
the naive approach is to give each container a volume pointing to each drive and configure multiple library paths. it works but it's messy - apps have to be configured separately per drive, and you're manually deciding which drive gets what.
what mergerfs does and how it works
mergerfs is a FUSE-based union filesystem for Linux. it merges multiple directories (or entire drives) into a single mount point. reads come from whichever drive has the file. writes go where the mergerfs policy decides.
/mnt/drive-a/
/mnt/drive-b/
/mnt/drive-c/
↓ mergerfs
/mnt/media/ ← apps see this, drives are transparent
the policy used here is mfs (most free space) — new files always land on whichever drive has the most room available. no manual balancing needed.
moveonenospc=true handles the edge case where a drive fills up mid-write — mergerfs transparently moves the file to another drive instead of failing.
mergerfs fstab entry
/mnt/drive-a:/mnt/drive-b:/mnt/drive-c /mnt/media fuse.mergerfs \
defaults,allow_other,use_ino,category.create=mfs,moveonenospc=true,\
dropcacheonclose=true,nofail 0 0
the nofail option is important — if a drive isn't available at boot, the system still comes up instead of dropping to emergency mode.
docker compose volumes with mergerfs
with mergerfs in place, Docker compose volumes simply point to subdirectories of the merged mount:
volumes:
media_movies:
driver: local
driver_opts:
type: none
device: /mnt/media/movies
o: bind
media_tv:
driver: local
driver_opts:
type: none
device: /mnt/media/tv
o: bind
containers get /movies, /tv, /downloads - they have no idea they're spread across three drives. this is how Jellyfin, Sonarr, and Radarr all see one unified media library across multiple hard drives.
mergerfs docker gotchas
Docker caches volume definitions. if you change the device path in your compose and redeploy, the existing volume keeps the old path. you have to stop the stack, delete the stale volume in Portainer, then redeploy. docker volume inspect shows the actual path.
nested volume mounts don't work. if you try to mount volume B at /media/tv when volume A is already mounted at /media, Docker silently ignores the inner mount. use separate top-level paths — /movies, /tv, /downloads instead of /media/movies, /media/tv.
mergerfs must be mounted before Docker starts. if the server reboots and mergerfs isn't up yet when Docker tries to start containers, they'll fail. the fstab x-systemd.requires option handles this by making Docker wait — but the syntax matters: each dependency needs its own x-systemd.requires= entry, comma-separating them in one option doesn't work.
mergerfs vs raid - no redundancy
mergerfs is not RAID. if a drive dies, data on that drive is gone. for a media server library sourced from the internet this is acceptable - everything is re-downloadable. for anything irreplaceable like photos or documents, use ZFS or md-raid instead.
the tradeoff is simplicity. mergerfs is easier to set up than RAID, easy to expand (buy another NAS hard drive, add it to the fstab merge path), and has no overhead on reads. for a homelab media server with Jellyfin, Sonarr, and Radarr, it's the right tool. when expanding, stick with CMR (conventional magnetic recording) drives - SMR drives have terrible write performance under sustained load from download clients.
CMR - NAS Optimized - 3yr Rescue Data Recovery
Designed for multi-bay NAS and always-on storage workloads
view on amazonaffiliate link - helps support the blog
eli5
imagine you have three bookshelves but you want to treat them like one big shelf. mergerfs is like a card catalog system — it tracks which shelf each book is actually on, but shows you a single unified list. when you add a new book, it automatically picks whichever shelf has the most empty space. when you want to read a book, it finds it for you. the apps (Jellyfin, Sonarr, Radarr) just see one giant shelf and don't know or care that it's three separate pieces of furniture. the downside: there's no backup copy — if a shelf breaks, those books are gone. for movies you downloaded off the internet that's fine. for family photos, use something safer.