naxos-docs/docs/guides/installation.md

NaxOS Installation & Distribution Guide

1. Building the Bootable ISO

To build the streamlined NaxOS installer image from source using Nix:

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

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

   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!