4.2 KiB
NaxOS Documentation
Comprehensive Technical Architecture & Operations Guide (NixOS 26.05 & OpenZFS)
Architecture Specifications, API Reference, Migration Runbooks, and Bare-Metal Guides
Welcome to the comprehensive documentation repository for NaxOS, the declarative, appliance-like Network Attached Storage (NAS) operating system built on NixOS 26.05 and OpenZFS.
Visual Tour & Web Dashboard Showcase
1. Dashboard Overview
Sleek glassmorphism interface featuring circular storage capacity gauges, real-time ZFS ARC cache telemetry, active workloads, and safe declarative system rebuild triggers.
2. OpenZFS Storage Management
Declarative OpenZFS pool topology browser, dataset quota manager, snapshot timeline rollback, and pool health monitoring.
3. Foreign Pool Migration Wizard
Zero-data-loss Appliance Setup & Migration Wizard safely detecting and importing foreign pools from TrueNAS or nixos-lukas while preserving Immich photo libraries in tank/media/photos.
4. Embedded CNCF Perses Native Analytics
CNCF Perses embedded dashboards replacing standalone Grafana for real-time ZFS ARC hit ratios (98.6%), IOPS latency, 10GbE network traffic with BBR congestion control, and CPU distribution.
5. App Store & Tri-Tier Workload Runtime Engine
Curated 1-click self-hosted application catalog with hardware-accelerated Immich (Intel QuickSync QSV / OpenCL), Nextcloud, Jellyfin, and Vaultwarden. Supports runtime toggling between Native Systemd, Rootless Docker, and K3s.
Table of Contents
1. Architecture & Internals
- High-Level Architecture & Philosophy
- Declarative Backend & GitOps Engine
- OpenZFS Storage Engine & Pool Migration
- Workload App Engine & Tri-Tier Runtimes
- CNCF Perses Native Observability
2. User & Administrator Guides
3. Developer Manual
Ecosystem Repositories (naxos Organization)
| Repository | Description | Gitea URL |
|---|---|---|
naxos-os |
Core NixOS distribution, declarative modules, Flake, and ISO builder | git.lholz.de/naxos/naxos-os |
naxos-api |
Management Daemon, REST/WebSocket API, GitOps synchronization, ZFS engine | git.lholz.de/naxos/naxos-api |
naxos-ui |
Modern web dashboard, embedded Perses metrics, pool manager, app store | git.lholz.de/naxos/naxos-ui |
naxos-docs |
System architecture, migration tutorials, developer guides, and API specs | git.lholz.de/naxos/naxos-docs |