88 lines
3.0 KiB
Markdown
88 lines
3.0 KiB
Markdown
# 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**.
|
|
|
|
|
|
|
|
---
|
|
|
|
## 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!
|