80 lines
4.2 KiB
Markdown
80 lines
4.2 KiB
Markdown
<p align="center">
|
|
<img src="docs/images/logo.svg" alt="NaxOS Logo" width="140" height="140" />
|
|
</p>
|
|
|
|
<h1 align="center">NaxOS Documentation</h1>
|
|
|
|
<p align="center">
|
|
<b>Comprehensive Technical Architecture & Operations Guide (NixOS 26.05 & OpenZFS)</b>
|
|
<br />
|
|
Architecture Specifications, API Reference, Migration Runbooks, and Bare-Metal Guides
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="https://git.lholz.de/naxos/naxos-docs/actions"><img src="https://git.lholz.de/naxos/naxos-docs/actions/workflows/ci.yaml/badge.svg" alt="Documentation Validation" /></a>
|
|
<a href="https://git.lholz.de/naxos/-/packages"><img src="https://img.shields.io/badge/package-gitea%20registry-blue.svg" alt="Gitea Packages" /></a>
|
|
<a href="https://git.lholz.de/naxos/naxos-docs"><img src="https://img.shields.io/badge/nixos-26.05-5277C3.svg?logo=nixos&logoColor=white" alt="NixOS 26.05" /></a>
|
|
</p>
|
|
|
|
---
|
|
|
|
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](docs/architecture/overview.md)
|
|
- [Declarative Backend & GitOps Engine](docs/architecture/declarative-backend.md)
|
|
- [OpenZFS Storage Engine & Pool Migration](docs/architecture/storage-engine.md)
|
|
- [Workload App Engine & Tri-Tier Runtimes](docs/architecture/app-engine.md)
|
|
- [CNCF Perses Native Observability](docs/architecture/perses-analytics.md)
|
|
|
|
### 2. User & Administrator Guides
|
|
- [Installation & Live ISO Guide](docs/guides/installation.md)
|
|
- [Migration Guide: Transitioning from `nixos-lukas` to NaxOS](docs/guides/migration-from-nixos-lukas.md)
|
|
|
|
### 3. Developer Manual
|
|
- [Management Daemon REST & WebSocket API Reference](docs/development/api-reference.md)
|
|
- [Contributing & Development Workflow](docs/development/contributing.md)
|
|
|
|
---
|
|
|
|
## Ecosystem Repositories (`naxos` Organization)
|
|
|
|
| Repository | Description | Gitea URL |
|
|
| :--- | :--- | :--- |
|
|
| [`naxos-os`](https://git.lholz.de/naxos/naxos-os) | Core NixOS distribution, declarative modules, Flake, and ISO builder | [git.lholz.de/naxos/naxos-os](https://git.lholz.de/naxos/naxos-os) |
|
|
| [`naxos-api`](https://git.lholz.de/naxos/naxos-api) | Management Daemon, REST/WebSocket API, GitOps synchronization, ZFS engine | [git.lholz.de/naxos/naxos-api](https://git.lholz.de/naxos/naxos-api) |
|
|
| [`naxos-ui`](https://git.lholz.de/naxos/naxos-ui) | Modern web dashboard, embedded Perses metrics, pool manager, app store | [git.lholz.de/naxos/naxos-ui](https://git.lholz.de/naxos/naxos-ui) |
|
|
| [`naxos-docs`](https://git.lholz.de/naxos/naxos-docs) | System architecture, migration tutorials, developer guides, and API specs | [git.lholz.de/naxos/naxos-docs](https://git.lholz.de/naxos/naxos-docs) | |