Migrate from TrueNAS SCALE¶

This guide covers moving from TrueNAS SCALE to Eight.ly OS. Whether you're hitting TrueNAS's app ecosystem limits or want to use mixed drive sizes without ZFS constraints, this walkthrough gets you migrated with your data intact.

Concept mapping¶

Pre-migration checklist¶

Before starting, gather this from your TrueNAS system:

• Export pool configuration. System > General > Save Config. This saves your TrueNAS configuration — useful if you need to roll back.
• Document your dataset layout. Record the hierarchy: pool/dataset/child-dataset paths, quotas, compression settings, and any special properties.
• Inventory your apps. List every installed app/chart, its version, and configuration. Note any custom helm values.
• Record share configuration. For each SMB/NFS share: path, permissions, allowed hosts/users.
• Note your network config. IP address, gateway, DNS, VLANs, LACP bonds.
• Verify pool health. Run zpool status and make sure all pools show ONLINE with no errors. Resolve any degraded vdevs before migrating.
• Check snapshot usage. List snapshots with zfs list -t snapshot. Decide which you need to preserve.

Migration strategies¶

Recommended: Option A (import your existing pool). It is the least destructive path and keeps your snapshots. Choose Option C only if you actually want to leave ZFS, usually because your drives are mixed sizes and you want MergerFS to use every byte.

Option A: ZFS pool import (recommended)¶

sudo zpool import              # list importable pools
sudo zpool import <poolname>   # import it

The flow:

1. Install Eight.ly OS on a separate boot drive (SSD/NVMe recommended).
2. Boot into Eight.ly, attach the drives holding your TrueNAS pool, and open Storage.
3. Import your existing ZFS pool from the dashboard prompt, or from the web terminal:

   zpool import
   zpool import <pool-name>
   

4. Your datasets, data, and snapshots are immediately available.
5. Configure shares and apps in the Eight.ly dashboard.

Option B: ZFS send/receive to a new pool¶

Best for: restructuring your pool layout during migration.

1. Install Eight.ly OS on a new boot drive.
2. Create a new ZFS pool in Eight.ly with your desired layout.
3. Send snapshots from TrueNAS to the new pool:

   # On TrueNAS — create a migration snapshot
   zfs snapshot -r oldpool@migrate
   
   # Send to Eight.ly over SSH
   zfs send -R oldpool@migrate | ssh eightly-server zfs receive -F newpool
   

4. This preserves all data, snapshots, and child datasets.

Option C: Switch to MergerFS + SnapRAID (recommended — works today)¶

Best for: users with mixed drive sizes who are tired of ZFS's same-size-per-vdev requirement. This is a wipe-and-restore: your data must be copied somewhere else first, because the drives get reformatted. If your pool is healthy and your drives are matched, Option A is less work and less risk.

1. Install Eight.ly OS on a new boot drive.
2. Format drives individually (XFS or ext4).
3. Pool them with MergerFS — any size, any mix. The Storage page builds the pool for you.
4. Rsync data from TrueNAS:

   rsync -avP --progress truenas:/mnt/pool/media/ /mnt/storage/media/
   rsync -avP --progress truenas:/mnt/pool/appdata/ /opt/appdata/
   

5. Set up SnapRAID with one or more parity drives.

App migration¶

TrueNAS SCALE's app ecosystem has been through several transitions (Kubernetes-based charts, TrueCharts, and now Docker). Eight.ly uses standard Docker Compose from the start.

For each app:

1. Search for it in Eight.ly's App Store (3,200+ apps).
2. Deploy it — Eight.ly generates a compose file with defaults.
3. Copy your app's config/data from the TrueNAS dataset to Eight.ly's /opt/appdata/<app>/ directory.
4. Update volume mounts in the compose file if your paths differ.
5. Start the container.

Most popular apps (Plex, Jellyfin, *arr stack, Nextcloud, Home Assistant, etc.) are available in the catalog using the same Docker images.

Storage setup¶

Keeping ZFS¶

Pool creation and management work from the Storage page, including importing a pool detected on attached disks. Once you've imported your pool (Option A), manage it from Storage in the Eight.ly dashboard — create datasets, schedule snapshots, and monitor health.

Switching to MergerFS + SnapRAID¶

1. Pool your formatted drives with MergerFS from the Storage page.
2. Designate parity drives for SnapRAID.
3. Schedule daily SnapRAID syncs.

MergerFS + SnapRAID is not a replacement for ZFS in every scenario. ZFS is better for data integrity guarantees and instant snapshots. MergerFS + SnapRAID is better for flexibility with mixed hardware and drive-by-drive recovery.

What you gain¶

• 3,200+ apps vs TrueNAS's ~100 charts
• Nova AI — natural language server management
• Mixed drive support via MergerFS + SnapRAID (no same-size requirement)
• Web terminal with tmux built in
• Docker Compose native — no Kubernetes complexity
• EBS backup server and remote agent included free
• A command line tool and an MCP server — eosctl for scripting, or connect an AI assistant to your box

What's different¶

• Docker, not Kubernetes. Apps deploy as Docker Compose stacks, not helm charts. Simpler to configure and debug.
• Flat directory structure. Eight.ly uses standard Linux paths (/opt/appdata/, /mnt/storage/) instead of ZFS dataset hierarchies for app data. Imported ZFS datasets still work — the apps just mount paths differently.
• Different permissions model. TrueNAS has ACL-heavy permission management tied to datasets. Eight.ly uses standard Linux permissions (uid/gid) with PUID/PGID environment variables for containers.
• New dashboard. Different layout, different navigation. The monitoring, storage, and app management views are all in one UI rather than spread across TrueNAS's tabbed interface.

Troubleshooting¶

zpool import doesn't find my pool.

Check that the drives are detected with lsblk. If the pool was exported cleanly from TrueNAS, zpool import should find it. If not, try zpool import -f <pool-name> to force import. If drives were part of a multipath config, you may need to specify device paths explicitly.

Permission errors after migration.

TrueNAS uses ACLs extensively. Eight.ly containers expect standard PUID/PGID ownership. Fix with:

chown -R 1000:1000 /opt/appdata/<app>/

Adjust the uid/gid to match the PUID/PGID in your container's environment variables.

My app's database won't start after copying data.

Some apps (especially those using PostgreSQL or MariaDB) are sensitive to being moved between architectures or file systems. If the database won't start, check the container logs (docker logs <container>). You may need to export/import the database rather than copying raw files.

ZFS performance is different than TrueNAS.

Verify that ZFS ARC size is configured appropriately. Eight.ly defaults may differ from TrueNAS's tuning. Check /etc/modprobe.d/zfs.conf and adjust zfs_arc_max if needed.