Migration Guide: Migrating from `nixos-lukas` (Hulk NAS) to NaxOS

This guide details how to transition an existing custom NixOS NAS (specifically the hulk setup found in nixos-lukas) to a declarative NaxOS appliance without data loss, preserving existing OpenZFS pools and critical application data (such as your Immich photo library).

IMPORTANT: Data Safety Guarantee The nixos-lukas repository is strictly read-only reference material. Do not make changes to it. All new configuration is managed via NaxOS.

1. Inventory of the Existing `hulk` Setup

In nixos-lukas/modules/system/hulk/nas.nix, the storage topology is:

Pool Name: tank
Key Datasets:
- tank/media: General media library
- tank/media/photos: Immich Photo Library (critical data)
- tank/backup: Backup share
- tank/time-machine: macOS Time Machine backup target
- tank/scans & tank/paperless-incoming: Paperless ingestion
- tank/container: Docker container storage root
Kernel Tuning: ARC limited to 4GB (zfs.zfs_arc_max=4294967296).
Services: Immich with Intel GPU acceleration (/dev/dri/renderD128), Samba with vfs_fruit, NFS exports.

2. Pre-Migration Verification (On Legacy Host)

Before shutting down or booting the NaxOS installer on the NAS machine:

Verify ZFS Pool Status:
```
zpool status tank
```
Ensure the pool is in an ONLINE state with 0 errors.

Ensure Clean Pool Export:

# Stop write services
systemctl stop immich docker smbd nfs-server

# Export pool cleanly
sudo zpool export tank

3. Importing `tank` into NaxOS via the Web Dashboard

Boot into NaxOS.
Open the Web Dashboard at http://naxos.local (or appliance IP).
Navigate to Storage & ZFS -> Pool Migration.
The NaxOS Migration Engine automatically detects the foreign tank pool:
- Status will show ONLINE
- Disks will list the member drive IDs
Click Safe Import & Adopt:
- NaxOS executes:
```
zpool import -N -f tank
```
- -N imports the pool without mounting, allowing NaxOS to audit and map dataset mountpoints safely.
The pool and all sub-datasets (tank/media/photos, tank/backup, etc.) will appear under Active Datasets.

4. Automatic Declarative Configuration

When adopted, NaxOS automatically commits the following into your GitOps repository:

services.naxos.storage = {
  enable = true;
  arcMaxBytes = 4294967296; # Preserves 4GB limit
  importExistingPools = [ "tank" ];
};

5. Restoring Immich & Hardware Acceleration

Navigate to App Store -> Immich Photo Hub.
Select Native Systemd runtime.
Configure the media path: /tank/media/photos.
Click Deploy Workload.
NaxOS activates Immich, binds Intel QuickSync (/dev/dri/renderD128), starts Redis and PostgreSQL, and mounts your existing photo library intact!

2.9 KiB Raw Blame History

Migration Guide: Migrating from nixos-lukas (Hulk NAS) to NaxOS

1. Inventory of the Existing hulk Setup