naxos-docs/docs/guides/installation.md

1. Downloading & Building the Bootable ISO

Direct ISO Download

You can download the official pre-built NaxOS installation media directly from Gitea:

• Gitea Release Page: https://git.lholz.de/naxos/naxos-os/releases
• Direct Package Download: Download NaxOS Installer ISO

Building the ISO from Source

To build the streamlined NaxOS installer image from source using Nix on any x86_64 Linux machine:

# Build directly from the remote flake:
nix build git+https://git.lholz.de/naxos/naxos-os.git#iso

# Or clone and build locally:
git clone https://git.lholz.de/naxos/naxos-os.git
cd naxos-os
nix build .#iso

The output bootable ISO will be generated at ./result/iso/naxos-installer-*.iso.

---

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 physical disk discovery.
   • Step 2: Storage architecture choice (Create fresh ZFS pool vs. Safe foreign pool import from TrueNAS or nixos-lukas).
   • Step 3: Target OS disk selection (partitions EFI system partition and ext4 root partition).
   • Step 4: Network configuration (appliance hostname and DHCP / static IP).
   • Step 5: Administrator credentials and SSH public keys.
   • Step 6: Automated installation and deployment.

What Does the Installer Actually Deploy?

During Step 6, naxos-installer:

1. Installs the NaxOS NixOS Modules: Deploys declarative appliance modules into /mnt/etc/nixos/naxos-os.
2. Installs the NaxOS Web Dashboard (naxos-ui): Unpacks the compiled React SPA into /mnt/opt/naxos/ui/dist.
3. Installs the NaxOS Management Daemon (naxos-api): Deploys the Node.js fastify backend daemon into /mnt/opt/naxos/api.
4. Configures Appliance Systemd Services: Enables services.naxos.api (port 8088), services.naxos.ui (Nginx reverse proxy on port 80/443), services.naxos.perses (CNCF Perses metrics on 8080), Samba SMB with Time Machine, and OpenZFS automated scrub/snapshots.
5. Executes nixos-install: Compiles and activates the complete appliance generation.

---

4. Post-Installation First Boot

After the system reboots:

1. Access the web dashboard by navigating to http://naxos.local (or http://<ip-address>).
2. Log in using your administrator credentials.
3. The NaxOS dashboard and management daemon are live and ready for operation!