migration to NixOS

unRAID to NixOS Migration Guide

Overview

This guide details the migration from unRAID to NixOS while preserving array data using SnapRAID + MergerFS as a replacement for unRAID's array management.

Prerequisites

All important data backed up to external location
Current unRAID configuration documented
USB drive for NixOS installation (8GB+)
Physical access to server
Network connectivity for installation

Notes

Completely refactor this process to:
- Leverage disko to build NixOS drive layout
- Deploy using deploy_server script
- Ensure data and array drives aren't referenced during deployment to avoid data loss

Phase 1: Documentation & Preparation

1.1 Document Current Drive Configuration

On the unRAID server, run:

# Get all drive UUIDs and info
lsblk -o NAME,SIZE,TYPE,MOUNTPOINT,UUID,FSTYPE > ~/drive-info.txt

# Get detailed filesystem info
blkid > ~/blkid-info.txt

# Document array configuration
cat /boot/config/disk.cfg > ~/disk-config.txt

# List all shares
ls -la /mnt/user/ > ~/shares.txt

# Get Docker container info
docker ps -a --format "table {{.Names}}\t{{.Image}}\t{{.Ports}}" > ~/docker-containers.txt

# Export Komodo configuration
docker inspect komodo > ~/komodo-inspect.json

# Copy entire Komodo appdata
cd /mnt/user/appdata
tar -czf ~/komodo-appdata-backup.tar.gz komodo/

1.2 Identify The Drives

From the output above, identify:

Boot drive: Usually smallest SSD (for NixOS installation)
Array drives: Data drives (disk1, disk2, etc.)
Cache drives: appdata and downloads caches

Create a mapping like:

Boot: /dev/sda (120GB SSD)
Disk1: /dev/sdb (4TB) - UUID: abc123...
Disk2: /dev/sdc (4TB) - UUID: def456...
Disk3: /dev/sdd (6TB) - UUID: ghi789...
Cache-appdata: /dev/sde (500GB SSD) - UUID: jkl012...
Cache-downloads: /dev/sdf (1TB SSD) - UUID: mno345...

1.3 Transfer Documentation Off Server

# Copy all documentation to local machine
scp root@unraid-ip:~/*-info.txt .
scp root@unraid-ip:~/komodo-appdata-backup.tar.gz .

Phase 2: NixOS Installation

2.1 Create NixOS Installation Media

On the workstation:

# Download NixOS ISO
curl -LO https://channels.nixos.org/nixos-24.05/latest-nixos-minimal-x86_64-linux.iso

# Write to USB (adjust /dev/sdX to the USB drive)
sudo dd if=latest-nixos-minimal-x86_64-linux.iso of=/dev/sdX bs=4M status=progress
sync

2.2 Boot NixOS Installer

Insert USB into server
Boot from USB (typically F11/F12 for boot menu)
Select NixOS installation media

2.3 Prepare Installation Environment

Once booted to NixOS installer:

# Set root password for SSH access
passwd

# Start SSH for remote installation
systemctl start sshd

# Find IP address
ip addr show

# Note the IP, then from the workstation:
ssh root@<nixos-ip>

Phase 3: Disk Preparation (CRITICAL!)

3.1 Verify Array Drives Are Intact

# List all drives - verify array drives are present
lsblk

# Verify filesystems (should match documentation)
blkid

CRITICAL: Do NOT proceed if drives are missing or UUIDs don't match!

3.2 Prepare Boot Drive ONLY

We only format the boot drive. Array drives remain untouched.

# Identify boot drive (smallest SSD, typically)
lsblk

# Set boot drive variable
BOOT_DRIVE=/dev/sda  # ADJUST THIS!

# Partition boot drive
parted $BOOT_DRIVE -- mklabel gpt
parted $BOOT_DRIVE -- mkpart ESP fat32 1MB 512MB
parted $BOOT_DRIVE -- set 1 esp on
parted $BOOT_DRIVE -- mkpart primary 512MB 100%

# Format partitions
mkfs.vfat -n BOOT ${BOOT_DRIVE}1
mkfs.btrfs -L nixos ${BOOT_DRIVE}2

# Create BTRFS subvolumes
mount ${BOOT_DRIVE}2 /mnt
btrfs subvolume create /mnt/@root
btrfs subvolume create /mnt/@nix
btrfs subvolume create /mnt/@persist
umount /mnt

# Mount for installation
mount -o subvol=@root ${BOOT_DRIVE}2 /mnt
mkdir -p /mnt/boot /mnt/nix /mnt/persist
mount ${BOOT_DRIVE}1 /mnt/boot
mount -o subvol=@nix ${BOOT_DRIVE}2 /mnt/nix
mount -o subvol=@persist ${BOOT_DRIVE}2 /mnt/persist

3.3 Create Mount Points for Array Drives

# Create directories for array drives
mkdir -p /mnt/persist/mnt/{disk1,disk2,disk3,cache-appdata,cache-downloads,storage}

Phase 4: NixOS Configuration

4.1 Generate Base Configuration

nixos-generate-config --root /mnt

4.2 Update Configuration Files

I'll need to edit /mnt/etc/nixos/configuration.nix and create the additional files.

Instead, let's use the configuration files I created. On the workstation:

# Copy configuration files to the server
scp crate-server-config.nix root@<nixos-ip>:/mnt/etc/nixos/configuration.nix
scp disk-config.nix root@<nixos-ip>:/mnt/etc/nixos/
scp hardware.nix root@<nixos-ip>:/mnt/etc/nixos/
scp snapraid.nix root@<nixos-ip>:/mnt/etc/nixos/

4.3 Update Hardware Configuration with Real UUIDs

Back on the NixOS installer, edit the hardware.nix file:

nano /mnt/etc/nixos/hardware.nix

Replace the placeholder UUIDs with the actual drive UUIDs from Phase 1.

IMPORTANT NOTES:

Verify filesystem types match (XFS, ext4, BTRFS)
Use UUIDs, not device names (/dev/sdX can change)
Double-check each UUID matches the correct drive

Example of what to update:

# Replace this:
device = "/dev/disk/by-uuid/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";

# With your actual UUID:
device = "/dev/disk/by-uuid/f8b3a124-9c76-4e11-a854-9b28f4e5d2a1";

Phase 5: Installation

5.1 Install NixOS

nixos-install

If there are errors, check:

All UUIDs are correct
Filesystem types match
Mount points exist
No syntax errors in .nix files

5.2 Set Root Password

nixos-install --root /mnt
# When prompted, set root password

5.3 Reboot

reboot

Remove USB drive when prompted.

Phase 6: Post-Installation Setup

6.1 First Boot Verification

After reboot, log in as root and verify:

# Check all filesystems mounted
df -h

# Should see:
# - /boot
# - /
# - /nix
# - /persist
# - /mnt/disk1, disk2, disk3
# - /mnt/cache-appdata, cache-downloads
# - /mnt/storage (MergerFS pool)

# Verify MergerFS is working
ls -la /mnt/storage

# Check SnapRAID status
snapraid status

6.2 Initialize SnapRAID

First-time setup for SnapRAID:

# Perform initial sync (this will take a while)
snapraid sync

# Verify status
snapraid status

# Check timers are active
systemctl list-timers

6.3 Restore Komodo Configuration

# Create Komodo directory
mkdir -p /mnt/cache-appdata/komodo

# Copy back your backup
# (Transfer from workstation first)
scp komodo-appdata-backup.tar.gz root@server-ip:/mnt/cache-appdata/

# Extract
cd /mnt/cache-appdata
tar -xzf komodo-appdata-backup.tar.gz

# Create docker-compose directory
mkdir -p /mnt/cache-appdata/komodo

# Copy docker-compose.yml
scp docker-compose.yml root@server-ip:/mnt/cache-appdata/komodo/

6.4 Start Komodo

cd /mnt/cache-appdata/komodo
docker-compose up -d

# Check logs
docker-compose logs -f

Phase 7: Verification & Testing

7.1 Data Integrity Check

# Verify I can access all your data
ls -R /mnt/storage | head -100

# Check some known files
ls -lh /mnt/storage/path/to/known/file

# Compare file counts (if I documented this from unRAID)
find /mnt/storage -type f | wc -l

7.2 Performance Testing

# Test read performance
dd if=/mnt/storage/large-file of=/dev/null bs=1M count=1000 status=progress

# Test write performance (to a test file)
dd if=/dev/zero of=/mnt/storage/test-file bs=1M count=1000 status=progress
rm /mnt/storage/test-file

7.3 SnapRAID Verification

# Run a scrub to verify data integrity
snapraid scrub -p 100

# Check for errors
snapraid status

Maintenance & Operations

Daily Operations

# Check array status
snapraid status

# Manual sync (if needed)
snapraid sync

# Check disk usage
df -h

# Check MergerFS pool
mergerfs.fsck /mnt/storage

Weekly Tasks

# Scrub data (auto-runs via systemd timer)
snapraid scrub

# Check system logs
journalctl -xe

# Update system
nixos-rebuild switch --upgrade

Adding a New Drive

When adding a new drive to the array:

Format the drive (e.g., XFS):

mkfs.xfs -L disk4 /dev/sdX

Get UUID:

blkid /dev/sdX

Update /etc/nixos/hardware.nix:

fileSystems."/mnt/disk4" = {
  device = "/dev/disk/by-uuid/NEW-UUID-HERE";
  fsType = "xfs";
  options = ["defaults"];
};

Update /etc/nixos/snapraid.nix:

data d4 /mnt/disk4
content /mnt/disk4/.snapraid.content

Rebuild and mount:

nixos-rebuild switch
mkdir -p /mnt/disk4
mount /mnt/disk4

Sync SnapRAID:

snapraid sync

Troubleshooting

Issue: Drive Won't Mount

# Check drive is detected
lsblk

# Check filesystem
blkid /dev/sdX

# Check for errors
dmesg | grep sdX

# Try manual mount
mount -t xfs /dev/sdX /mnt/diskX

Issue: MergerFS Not Working

# Check mounts
df -h | grep disk

# Verify fuse
lsmod | grep fuse

# Remount
umount /mnt/storage
mount /mnt/storage

Issue: Docker Won't Start

# Check service
systemctl status docker

# Check logs
journalctl -u docker -n 50

# Restart
systemctl restart docker

Issue: Komodo Container Problems

cd /mnt/cache-appdata/komodo

# Check status
docker-compose ps

# View logs
docker-compose logs

# Restart
docker-compose restart

# Full reset
docker-compose down
docker-compose up -d

Key Differences from unRAID

Feature	unRAID	NixOS + SnapRAID
Array Management	Proprietary	MergerFS (pooling)
Parity	Real-time	SnapRAID (scheduled)
Configuration	Web UI	Declarative files
Updates	Click button	`nixos-rebuild switch`
Docker	Web UI	docker-compose
User Shares	Built-in	Manual via MergerFS

Important: SnapRAID parity is NOT real-time like unRAID. Run syncs after bulk changes:

snapraid sync

Emergency Recovery

If something goes wrong:

Boot from USB again

Boot NixOS installer USB
Mount your boot drive:

mount -o subvol=@root /dev/sda2 /mnt
mount /dev/sda1 /mnt/boot
mount -o subvol=@nix /dev/sda2 /mnt/nix

Chroot and fix:

nixos-enter --root /mnt
# Make fixes
nixos-rebuild switch
exit
reboot

Array Data Recovery

Your array drives are never touched during installation. You can:

Boot any Linux live USB
Mount drives individually
Copy data off

Next Steps

Consider adding:

Parity drive: Add parity /mnt/parity/snapraid.parity to SnapRAID
Monitoring: Add Prometheus/Grafana for disk monitoring
SMART monitoring: Add smartd configuration
Automated backups: Configure borg or restic
Remote access: Add Tailscale/WireGuard
More containers: Expand Docker setup as needed

Support

If you run into issues:

Check logs: journalctl -xe
Check specific service: systemctl status servicename
Verify configs: nixos-rebuild dry-build
Check this documentation
Check NixOS documentation: https://nixos.org/manual/nixos/stable/