docs: complete NaxOS architectural specs, migration guides, API reference, and CI workflows

2026-09-04 00:15:21 +02:00
parent 2719f87e9e
commit ce7c125391
11 changed files with 490 additions and 2 deletions
@@ -0,0 +1,55 @@
+# NaxOS Installation & Distribution Guide
+
+## 1. Building the Bootable ISO
+
+To build the streamlined NaxOS installer image from source using Nix:
+
+```bash
+cd naxos-os
+nix build .#iso
+```
+
+The output will be located at `result/iso/naxos-installer-*.iso`.
+
+Alternatively, download the latest pre-built ISO from the Gitea Releases page:
+`https://git.lholz.de/naxos/naxos-os/releases`
+
+---
+
+## 2. Writing to USB Flash Drive
+
+Write the ISO image to a USB flash drive (replace `/dev/sdX` with your USB drive device):
+
+```bash
+# macOS
+sudo dd if=result/iso/naxos-installer-*.iso of=/dev/rdiskX bs=4M status=progress; sync
+
+# Linux
+sudo dd if=result/iso/naxos-installer-*.iso of=/dev/sdX bs=4M status=progress oflag=sync
+```
+
+---
+
+## 3. Running the Installer Wizard
+
+1. Insert the USB drive into your target hardware and boot in UEFI mode.
+2. The Live environment will automatically log in as `root` and start the interactive setup wizard:
+   ```bash
+   naxos-installer
+   ```
+3. Follow the guided steps:
+   - **Step 1**: System hardware inspection and disk discovery.
+   - **Step 2**: Storage architecture choice (Create fresh ZFS pool vs. Safe foreign pool import).
+   - **Step 3**: Target OS disk selection (installs bootloader and root system).
+   - **Step 4**: Network configuration (hostname and DHCP/static IP).
+   - **Step 5**: Administrator credentials and SSH public keys.
+   - **Step 6**: Automated installation and reboot.
+
+---
+
+## 4. Post-Installation First Boot
+
+After the system reboots:
+1. Access the web dashboard by navigating to `http://naxos.local` (or the IP displayed on console).
+2. Log in using your administrator credentials.
+3. Your NaxOS appliance is ready for service!
@@ -0,0 +1,85 @@
+# 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!