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!