Guide: Expand Jellyfin Media Sources with NFS Share Mount

Guides
1

The Premise

At the time of this writing StartOS doesn’t support multiple data drives. This can make it difficult to store large amounts of data like a media library which you would like to expose with Jellyfin for example. This guide aims to provide a way for users to leverage filebrowser-startos with an external (but perhaps low CPU) NAS to expand the storage capabilities of StartOS.

WARNING: Once an external share has been mounted to Filebrowser, caution should be exercised when creating a Filebrowser backup as all service data including the mounted NFS share will be encrypted and saved to the backup target. If data other than the mounted NFS share exists on Filebrowser that needs to be backed up, you might want to unmount the NFS share before backing up Filebrowser.

The Process

This guide assumes you already have NAS exposed on your LAN using NFS. Perfect Media Server has a great guide for setting up a home media server to accomplish the steps not covered in this guide, while leveraging the usability of StartOS.

  1. SSH into your StartOS server and elevate to root privileges with sudo -i

  2. Create a mountpoint for your NAS in Filebrowser i.e. mkdir /embassy-data/package-data/volumes/filebrowser/data/main/data/NAS/

  3. Create a postinit.sh script to mount the NFS share on each reboot of StartOS by running touch /media/embassy/config/postinit.sh

  4. Make the script executable by running chmod +x /media/embassy/config/postinit.sh

  5. Enter script contents to mount the NFS share (take care to replace <NFS_IP> with the IP address of your NFS share and </SHARE/PATH> with the path of the source directory to be mounted:)

    cat >> /media/embassy/config/postinit.sh<< EOF
#!/bin/bash

mount -t nfs <NFS_IP>:</SHARE/PATH> /embassy-data/package-data/volumes/filebrowser/data/main/data/NAS/
EOF

  6. Run sudo /usr/lib/startos/scripts/chroot-and-upgrade to install and persist across reboots dependencies required but not included in StartOS by default.

  7. Once in the chrooted environment, run apt install nfs-common - This package is required to mount the NFS share to a mountpoint on StartOS.

  8. Run exit to close out of the chrooted environment. This will restart StartOS.

  9. When you reopen Filebrowser you should see the contents of your NFS share at the mountpoint!

7 Likes
External RAID setup for NextCloud or (FileBrowser)
2

This guide was great, only hiccup was the the apt install nfs-common command failed at first, I needed to run apt-get update first. Figured I’d put this here in case anyone else runs into this problem and ends up scratching their head like me.

1 Like
3

would the same thing work with Samba?

4

Samba would be another approach that should work, but I haven’t tried it.

Feel free to reply on this thread with the steps taken if you are able to get Samba to work.

Jellyfin/Plex: add external storage?
5

Is this guide sill current for 0.4.0?

6

I just tried it, but I’m wondering if the directory structure has changed because I get this error on the first command. “mkdir: cannot create directory ‘/embassy-data/package-data/volumes/filebrowser/data/main/data/NAS/’: No such file or directory”

7

That’s why I was asking if the guide is still current for v0.4.0. Suspected that directory structure changes were likely.

8

0.4.0 is not an incremental upgrade to 0.3.5.1. It’s a completely different operating system. Almost nothing survived. This guide may be completely wrong for 0.4.0.

If you want to hack on this, do so at your own risk. There be dragons! The new path to the containers is:

/media/startos/data/package-data/volumes/

Please note, this is not a drop in replacement for the previous path. Just showing you where to look. The rest is up to you.

9

I worked with Claude to work this out, and here is my guide: Use at Your Own Risk.

Mounting an NFS Share into Filebrowser on StartOS 0.4

The official Start9 guide for mounting an NFS share into Filebrowser was written for StartOS 0.3.x and the paths no longer work on 0.4. This guide is an updated procedure tested on StartOS 0.4.0-beta.8.

Important order-of-operations note: Install and configure any other service that consumes Filebrowser’s volume (Jellyfin, etc.) before mounting the NFS share. StartOS’s pointer-volume bind mounts fail with mount exited with exit status: 32 if there’s an active NFS mount inside the source volume at the moment the dependent service tries to start up. Once the dependent service is running, NFS can be mounted underneath without issue.

What changed in 0.4

  • /embassy-data/ no longer exists. The data tree moved to /media/startos/data/.
  • /media/embassy/config/ moved to /media/startos/config/.
  • Services now run in LXC containers instead of Docker/Podman, but mount propagation from host into container still works.
  • Filebrowser’s actual serving root sits at data/data/ (yes, doubled), not data/main/data/ as in the old guide.

Procedure

1. Install and configure dependent services first

If any other StartOS service will consume Filebrowser’s volume (Jellyfin is the common case), install and start it before mounting NFS. If you skip this step and mount NFS first, the dependent service will fail to start with a mount exited with exit status: 32 error.

2. SSH in and become root

ssh start9@<your-server>.local
sudo -i

3. Install nfs-common via chroot-and-upgrade

/usr/lib/startos/scripts/chroot-and-upgrade

You’ll see “Syncing…” and the prompt will change. Then:

apt update
apt install nfs-common
exit

The exit triggers StartOS to rebuild its system image with nfs-common baked in (you’ll see mksquashfs running) and then reboot. This takes 10–20 minutes. Don’t interrupt it.

4. After reboot, SSH back in as root and find your NAS’s actual export path

sudo -i
showmount -e <NFS_IP>

The export path the NFS server advertises is often not the same as the path you see in your file manager when browsing the share. Use whatever showmount returns — that’s the authoritative path.

If showmount hangs, the most common causes are:

  • NFS service not enabled on the NAS
  • Host access not configured for your StartOS server’s IP
  • A firewall blocking the request

Consult your NAS’s documentation for enabling NFS and configuring host access. Most NAS systems require you to explicitly allow your client’s IP or subnet to connect.

5. Create the mountpoint at Filebrowser’s actual serving root

mkdir -p /media/startos/data/package-data/volumes/filebrowser/data/data/NAS/

6. Mount the NFS share

Replace <NFS_IP> with your NAS’s IP and <EXPORT_PATH> with the path from showmount:

mount -t nfs <NFS_IP>:<EXPORT_PATH> /media/startos/data/package-data/volumes/filebrowser/data/data/NAS/

Verify it worked:

echo /media/startos/data/package-data/volumes/filebrowser/data/data/NAS/*

You should see your share’s folders listed.

7. Refresh Filebrowser

Hard-refresh Filebrowser in your browser (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows). The NAS folder should appear at the home/root level alongside any other folders you have. Click in to confirm contents are visible.

8. Create a postinit.sh to remount on reboot

touch /media/startos/config/postinit.sh
chmod +x /media/startos/config/postinit.sh

cat > /media/startos/config/postinit.sh << 'EOF'
#!/bin/bash
# Sleep to let dependent services start before NFS is mounted into
# Filebrowser's volume. This avoids pointer-mount failures on services
# that bind-mount Filebrowser's data.
sleep 90
mount -t nfs <NFS_IP>:<EXPORT_PATH> /media/startos/data/package-data/volumes/filebrowser/data/data/NAS/
EOF

(Substitute your real <NFS_IP> and <EXPORT_PATH>.)

The 90-second sleep is a workaround for the pointer-mount conflict described at the top of this guide. Tune up or down as needed for your setup.

If a service that uses Filebrowser ever fails to start

Symptom: a service won’t start, and its logs show mount exited with exit status: 32.

Workaround:

sudo -i
umount /media/startos/data/package-data/volumes/filebrowser/data/data/NAS/

Start the service via the StartOS web UI. Once it’s fully up:

mount -t nfs <NFS_IP>:<EXPORT_PATH> /media/startos/data/package-data/volumes/filebrowser/data/data/NAS/

The service will continue running fine with the NFS mount restored.

Open question — does postinit.sh actually run on boot in 0.4?

I haven’t yet confirmed whether /media/startos/config/postinit.sh is wired to fire automatically at boot on 0.4. If you reboot and the mount is missing, postinit isn’t being honored on this version, and you’ll need to set up a systemd mount unit or /etc/fstab entry as the persistent solution instead. If anyone has tested this on 0.4, please reply with what you found.

Caveats

  • This was tested on StartOS 0.4.0-beta.8. Paths may shift again in future betas.
  • Browsing large folders through Filebrowser-over-NFS-over-LXC is slower than mounting NFS directly on your client device. Worth it for remote/web access; not the right tool for fast local browsing.
  • This procedure modifies host-level system config and installs packages via chroot-and-upgrade. If something goes wrong on a beta OS running production services, you may need to reinstall. Snapshot/back up before proceeding.
1 Like