Reboot to Reset? Fixing Docker NFS Mount Shadowing

I finally bit the bullet and got a NAS at home; I ended up going the UniFi route to add to the rest of my UniFi gear. Naturally, the first thing I wanted to do was get my home automation data off my server's local SSD and onto that new storage.

Everything worked great... until I did a routine server reboot.

When the system came back up, I navigated to my Home Assistant URL expecting my usual dashboard, but instead got the "Welcome! Let's get started" screen.

All that data, gone? No - just hiding. Here's what happened.

#The race condition

This usually happens because of a simple race condition. When your server reboots, Docker is often faster than the network mount. If the NAS isn't available the moment Docker tries to start the container, Docker doesn't wait - it just assumes you want to store data locally.

It creates a new folder on your local drive and starts a fresh install right there. If you check your mount point, the folders exist, but they're just empty shells on your local disk:

#The "shadow" effect

When I browsed directly to the network share in my file explorer, all my files were safe and sound. But on the server, Docker was already running with a file handle to those local empty directories.

Because Docker started before the mount was ready, the NAS data covered the local folder once it finally connected - but Docker was already attached to the local version on the SSD and stayed there.

#How to verify

If you suspect your local drive has shadowed your mount, run this command to see which physical drive is actually backing that folder:

#The "ghost" output (local SSD)

If you see your local system drive (like /dev/nvme0n1p2), you're looking at the empty local copy on your SSD:

#The "real" output (NAS)

This is what you want to see. When the NAS is correctly mounted, the output shows the NAS IP:

#The fix: clearing the shadows

To get your real data back, clear out those local empty directories so the NAS mount has nothing to hide behind.

1. Stop the containers: docker compose down
2. Unmount the NAS: sudo umount -l /mnt
3. Now that the NAS is unmounted, check /mnt directly. If there are files there, delete them.
4. Remount: sudo mount -a

#The permanent safety net

To stop this happening after the next reboot, update your docker-compose.yml to use a bind mount with create_host_path: false. This tells Docker not to start if the source path doesn't exist.

With create_host_path: false, the container will refuse to start if the NAS isn't mounted yet. A failed start is obvious and easy to fix. A silent fallback to local storage is neither.