# 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:

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

2. **Ensure Clean Pool Export**:
   ```bash
   # 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

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

![NaxOS Pool Migration Wizard and Dataset Browser](../images/migration-wizard.png)

---

## 4. Automatic Declarative Configuration

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

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

---

## 5. Restoring Immich & Hardware Acceleration

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