Migrate from Unraid¶

This guide covers moving from an Unraid server to Eight.ly OS. The process preserves your data and gets most of your apps running on Eight.ly with the same Docker images you're already using.

Concept mapping¶

Before starting, understand how Unraid concepts translate to Eight.ly:

Unraid	Eight.ly	Notes
Community Applications	App Store (3,200+ apps)	Same Docker images, larger catalog
Array (parity + data disks)	MergerFS pool + SnapRAID	Similar layout, different parity model — see the callout below
Cache pool	Cache mover	Similar concept, different config location
Shares	File Sharing page	SMB/NFS configured via the web UI
Docker tab	Docker page	Compose-native instead of XML templates
VMs tab	Infrastructure > VMs	KVM/QEMU with noVNC, same underlying tech
Unraid Connect	Not needed	Eight.ly is fully local, no cloud dashboard
Flash drive boot	Any boot drive	SSD, NVMe, USB — no hardware lock
User Scripts plugin	Web Terminal	Built-in tmux terminal, no plugin needed
CA Backup / Restore	EBS (included free)	Deduplication + encryption backup server

Parity works differently — this is not a 1:1 swap

Unraid's array uses real-time block parity: every write is protected the moment it lands. SnapRAID uses scheduled snapshot parity: files are only protected after the next snapraid sync runs. Anything written between syncs is unprotected — if a data disk dies before the next sync, files added or changed since the last sync are gone.

Two more consequences for migration:

Your Unraid parity disk is useless to SnapRAID. The parity formats are incompatible. SnapRAID builds its parity from scratch, so plan for the disk to be wiped and re-dedicated.
The initial parity build is a full read of every data disk. On a large array this is measured in days, not hours — an 80TB array can take several days of continuous disk activity before you have any parity protection at all. Your data is unprotected by parity until that first sync completes.

Pre-migration checklist¶

Before you touch anything, gather this information from your Unraid server:

Inventory your apps. Go to the Docker tab and note every running container, its image name, and version tag.
Document your volume mounts. For each container, record the host paths mapped into it (e.g., /mnt/user/appdata/plex:/config).
Note your share paths. Go to Shares and record each share name, included/excluded disks, and any special permissions.
Export Docker templates. Your templates live in /boot/config/plugins/dockerMan/templates-user/. Copy this directory to a USB drive or network share.
Back up your flash drive. Main > Flash > Flash Backup. This is your Unraid recovery safety net.
Record your network config. IP address, gateway, DNS, any VLANs or bonds.
Check your parity status. Make sure parity is valid before starting. Run a parity check if it hasn't been done recently.
Dry-run the install first. See below — don't skip this.

Dry-run the install on spare drives first¶

Before any data moves, install Eight.ly OS on the actual target hardware using spare or empty drives only — a spare SSD as the boot drive, nothing from your array plugged in. Confirm three things:

It boots. BIOS/UEFI settings, Secure Boot, and the boot drive all cooperate.
Every drive bay is visible. Plug a scratch disk into each bay (or at least each controller/backplane) and check it shows up in Storage > Disks. HBA and backplane surprises are much cheaper to find now.
Your network link comes up at full speed. Check the negotiated speed, not just "has an IP."

10GbE on Ugreen and other Aquantia-based boxes

Ugreen NAS boxes (and others using Aquantia/Marvell AQC113 10GbE NICs) work with the in-tree atlantic driver, which needs no separate firmware blob. A full 10000Mb/s link has been confirmed on a UGREEN DXP8800 Plus running Eight.ly OS itself. Checking the negotiated speed on your own first boot is still cheap insurance: check the speed, not just whether the port has an IP, before you commit to a multi-day data copy over it. Installing on a UGREEN DXP? See the UGREEN DXP notes — the firmware ships with M.2 boot disabled.

Only after the dry-run passes should you shut down Unraid and start the real migration.

Large arrays (10TB+)¶

The bigger the array, the less room you have for mistakes. At 10TB+ (and especially at 50-80TB), a failed migration isn't an evening of restores — it can be weeks. Before touching a large array:

Verify what your backup actually holds. "I have PBS" is not a backup — a restore you've tested is. List the backup contents and restore a sample of real files before you start. Backup jobs that silently excluded a share, stopped running months ago, or only covered appdata are found now or at the worst possible time.
Keep an independent copy that is NOT on the drives you're reusing. If your only copy of the data lives on the disks you're about to re-pool, you have no rollback if anything goes wrong mid-migration. The copy must survive the drives being wiped, re-cabled, or misdetected.
Keep the Unraid boot USB intact as your rollback. Don't wipe or repurpose it until the new pool is verified and the first full SnapRAID sync has completed. Until both are true, plugging the USB back in and booting Unraid is your escape hatch — the array config lives on that flash drive.
Do the bay-count and free-space math. You can't stage a copy of your data with zero free bays and a full array. Count physical bays, count spare drives, and work out where the staged copy physically lives before you start. If the answer is "nowhere," you need Option A (copy over the network to different hardware) or more disks — not optimism.

Migration strategies¶

Option A: Fresh install, migrate data over network¶

Best for: clean start, minimal risk.

Install Eight.ly OS on a new boot drive (SSD recommended).
Create a MergerFS + SnapRAID array from the Storage page. This formats the drives you select, which is fine here because they're new or empty. General config reference: Configuration.

Rsync data from Unraid over the network:

rsync -avP --progress /mnt/user/media/ eightly-server:/mnt/storage/media/
rsync -avP --progress /mnt/user/appdata/ eightly-server:/opt/appdata/

Recreate your apps in Eight.ly's App Store.

Option B: Replace boot drive, keep data drives¶

Best for: preserving data in place.

Shut down Unraid.
Remove the USB boot drive.
Install Eight.ly OS on a new boot drive (SSD/NVMe).
Boot into Eight.ly and pool your existing data drives with MergerFS (see below).
Your data is already on the drives — just point Eight.ly at the mount paths.

Your data is readable without reformatting

Unraid uses XFS or BTRFS for data drives, and Eight.ly mounts both.

The reason this works is worth understanding before you trust it: Unraid's md layer is only a parity shim. The filesystem sits directly on the raw partition, so /dev/sdb1 is a plain XFS volume that any Linux system can mount with Unraid nowhere in the picture. You can verify this on your own server before committing to anything:

lsblk -f          # your data partitions will show as xfs or btrfs

Parity disks are the exception — they carry no filesystem and will show blank.

Adopting drives that already hold data is built into the Storage page

When you create an array from the Storage page, the first choice is whether to build a new array or adopt existing disks. Choose adopt, and the wizard mounts your XFS/BTRFS data drives and pools them in place — it never formats a data disk. Your files stay exactly where they are.

The one destructive step is parity. SnapRAID's parity format is incompatible with Unraid's, so the parity drive you designate is wiped and its parity rebuilt from scratch. The wizard makes you type a confirmation before it touches that drive, and the wipe only ever applies to parity — not to the disks holding your data.

After adopting, kick off the first SnapRAID sync from the Storage page and let it run to completion — your data has no parity protection until it finishes.

Adopt limitations

A few honest boundaries of the adopt path:

Parity size: the parity drive must be at least as large as your largest data disk.
Multi-device BTRFS cache pools can't be adopted through the wizard. Move the cache contents off first, then reformat the cache devices once the array is up.
Encrypted (LUKS) disks aren't supported by the adopt path.
The initial SnapRAID sync must be started from the Storage page and takes a long time on large arrays — days, not hours. Until it completes, the new parity offers no protection.

Appendix: adopting drives manually over SSH

The adopt wizard is the supported path. If you prefer to do it by hand — or want to understand what the wizard does — the same result over SSH or the web terminal looks like this:

# 1. Find your Unraid data drives (XFS/BTRFS partitions)
lsblk -f

# 2. Mount each data drive
sudo mkdir -p /mnt/disk1 /mnt/disk2
sudo mount /dev/sdb1 /mnt/disk1
sudo mount /dev/sdc1 /mnt/disk2

# 3. Pool them with MergerFS
sudo mkdir -p /mnt/storage
sudo mergerfs -o category.create=pfrd,allow_other,minfreespace=20G,fsname=mergerfs,inodecalc=path-hash,noforget \
  /mnt/disk1:/mnt/disk2 /mnt/storage

These are the same options Eight.ly OS itself builds for a new array. category.create=pfrd picks the destination disk at random, weighted by free space, when a new file is created — a different placement policy than Unraid's, but one Eight.ly's own cache/mover tooling expects; a cache-backed array instead uses category.create=ff (first branch with room). minfreespace=20G spills over to another disk when the preferred one gets close to full. inodecalc=path-hash matters if you ever compare inode numbers across the pool by hand: each path gets a synthesized, stable inode rather than the filesystem's real one, which is what makes NFS handles and hardlink detection work correctly across a union — don't substitute a plain use_ino here, it isn't equivalent.

To make it survive reboots, add the disk mounts and the pool to /etc/fstab (use UUID= from lsblk -f, not /dev/sdX names — those can change between boots):

UUID=<disk1-uuid>  /mnt/disk1   xfs       defaults  0 2
UUID=<disk2-uuid>  /mnt/disk2   xfs       defaults  0 2
/mnt/disk1:/mnt/disk2  /mnt/storage  fuse.mergerfs  category.create=pfrd,allow_other,minfreespace=20G,fsname=mergerfs,inodecalc=path-hash,noforget  0 0

Once mounted, the pool shows up in the dashboard and everything else in this guide works as described.

Option C: ZFS migration¶

Best for: same-size drives, and you want checksums, snapshots and real-time redundancy rather than scheduled parity.

Install Eight.ly OS on a new boot drive.
Create a ZFS pool from the Storage page using new or reformatted drives.
Rsync data from Unraid to the new ZFS pool.
Once verified, wipe the old Unraid drives and add them as a second vdev or a separate pool.

This reformats drives

ZFS cannot adopt an existing Unraid filesystem — the disks are wiped. Only take this route if you have enough spare capacity to hold a full copy of your data elsewhere, or a backup you have actually restored from.

ZFS wants matched drives

A vdev is limited by its smallest member, so mixed drive sizes waste capacity. If your array is a pile of different-size disks accumulated over years, MergerFS + SnapRAID (Options A/B) will use every byte and ZFS will not.

App migration¶

Most Unraid Docker containers use the same images available in Eight.ly's catalog (linuxserver.io, hotio, etc.). The migration process for each app:

Search for the app in Eight.ly's App Store.
Deploy it — Eight.ly generates a Docker Compose file with sensible defaults.
Update volume mounts to match your Unraid paths (or update paths to Eight.ly's /opt/appdata/<app>/ convention).
Copy the app's config data from your Unraid appdata to the new path if you changed it.
Start the container.

Preserving app data

If you kept your appdata directory structure intact (Option B), point Eight.ly containers at the same paths. Most apps will pick up their existing config and database files without any reconfiguration.

Storage setup¶

MergerFS + SnapRAID (recommended for mixed drives)¶

MergerFS pools your data drives into a single mount point, and SnapRAID provides parity protection. Unlike Unraid's array, there's no start/stop cycle — drives are always accessible.

Pool your data drives from the Storage page. For new or empty drives, build a new array — that path formats them. For drives that already hold data, choose the adopt option — it mounts and pools your existing disks without formatting them (see the Option B callout above for details and limitations).
Designate one or more parity drives for SnapRAID. Remember: an old Unraid parity disk gets wiped — its parity format is incompatible.
Configure a SnapRAID sync schedule (daily recommended).
Run the first snapraid sync and let it finish — you have no parity protection until it does (days, on large arrays).

ZFS¶

Create and import ZFS pools from the Storage page. Choose ZFS when your drives are the same size and you want checksumming, snapshots and real-time redundancy.

ZFS is limited by its smallest drive in each vdev, so mixed drive sizes waste capacity. A collection of different-size disks is a better fit for MergerFS + SnapRAID, which uses every byte of every drive.

What you gain¶

3,200+ apps vs Unraid's ~200 Community Applications
Nova AI — ask questions about your server in plain English
No USB key — install on any drive, no hardware-locked license
Web terminal with tmux — no SSH needed for quick tasks
EBS backup server and remote agent included free — deduplication + encryption
A command line tool and an MCP server — eosctl for scripting, or connect an AI assistant to your box, both generated from the same API the dashboard uses

Mobile app

Eight.ly Mobile has not shipped yet. The dashboard is a normal responsive web page, so you can already manage your box from a phone or tablet browser — see Mobile App.

What's different¶

No array start/stop. MergerFS pools are always mounted. There's no "starting the array" step after boot.
Docker Compose, not XML templates. Eight.ly uses standard compose files. Your Unraid XML templates won't import directly, but the same Docker images are available.
Different share permissions model. Eight.ly configures SMB/NFS shares through its own UI rather than Unraid's per-share settings page.
New dashboard layout. The navigation and monitoring views are different. Give yourself a day to learn where things are.

Troubleshooting¶

My XFS drives aren't showing up.: Make sure the drives are detected in Storage > Disks. Eight.ly can mount XFS drives — they don't need reformatting. If a drive doesn't appear, check lsblk in the web terminal.
My app can't find its config files.: Volume mount paths probably changed. Compare the old Unraid template's host path with what Eight.ly is using. Update the compose file's volume mounts to point at the correct location.
SnapRAID parity check is slow.: Initial parity sync takes time proportional to your data size. Subsequent syncs are incremental and much faster. This is normal behavior, not a bug.
I miss a specific Unraid plugin.: Check the Eight.ly App Store — many plugin functions are either built-in (monitoring, backup, terminal) or available as Docker containers. If something is genuinely missing, request it on Discord.