66 lines
3.8 KiB
Markdown
66 lines
3.8 KiB
Markdown
<p align="center">
|
|
<img src="docs/images/logo.svg" alt="NaxOS Logo" width="140" height="140" />
|
|
</p>
|
|
|
|
<h1 align="center">NaxOS Management Daemon & API</h1>
|
|
|
|
<p align="center">
|
|
<b>Core Orchestration Brain for NaxOS Appliance (NixOS 26.05 & OpenZFS)</b>
|
|
<br />
|
|
Fastify REST & SSE Daemon with Declarative NixOS Compiler & GitOps Engine
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="https://git.lholz.de/naxos/naxos-api/actions"><img src="https://git.lholz.de/naxos/naxos-api/actions/workflows/ci.yaml/badge.svg" alt="Gitea Actions" /></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-api"><img src="https://img.shields.io/badge/nixos-26.05-5277C3.svg?logo=nixos&logoColor=white" alt="NixOS 26.05" /></a>
|
|
</p>
|
|
|
|
---
|
|
|
|
The **NaxOS Management Daemon** serves as the core orchestration brain of the NaxOS storage appliance. It bridges web dashboard interactions with underlying declarative NixOS 26.05 module generation, OpenZFS primitives, GitOps synchronization, and workload lifecycle controls.
|
|
|
|
## Appliance Interface Showcase
|
|
|
|
| Overview & Telemetry | OpenZFS Storage Engine |
|
|
| :---: | :---: |
|
|
|  |  |
|
|
| **Live System & Storage Telemetry** | **App Store & Runtimes** |
|
|
|  |  |
|
|
|
|
## Core Capabilities
|
|
|
|
- **Declarative NixOS Compiler**: Translates REST API actions directly into standard NixOS module syntax (`generated-naxos-config.nix`), validated before activating via `nixos-rebuild switch`.
|
|
- **GitOps Synchronization Engine**: Every configuration modification creates an atomic local Git commit and automatically pushes to the remote repository (e.g. Gitea) with instant 1-click rollback capability.
|
|
- **Native OpenZFS Management**: Full REST API for pools, vdevs, datasets, quotas, snapshots, scrubs, and TRIM.
|
|
- **Foreign Pool Migration**: Zero-data-loss safe discovery and import of foreign ZFS pools from TrueNAS or raw NixOS setups like `nixos-lukas`.
|
|
- **Tri-Tier Workload Engine**: Manages native NixOS systemd services (e.g., Immich with Intel QuickSync / OpenCL hardware acceleration), rootless Docker Compose, and lightweight K3s clusters.
|
|
- **Seamless Real-time Telemetry & SSE Logs**: Delivers live ZFS ARC metrics, pool I/O stats, CPU/memory distributions, and streams real-time journald logs.
|
|
|
|
## REST API Overview
|
|
|
|
| Endpoint | Method | Description |
|
|
| :--- | :--- | :--- |
|
|
| `/api/v1/system/status` | `GET` | Appliance health, CPU, RAM, ARC hit ratio |
|
|
| `/api/v1/system/rebuild` | `POST` | Triggers declarative rebuild; streams output via SSE |
|
|
| `/api/v1/storage/pools` | `GET`, `POST` | List and create ZFS pools |
|
|
| `/api/v1/storage/unimported` | `GET` | Scan for unimported foreign pools |
|
|
| `/api/v1/storage/import` | `POST` | Safely import foreign pool without data loss |
|
|
| `/api/v1/storage/datasets` | `GET`, `POST` | Manage ZFS datasets, quotas, recordsize |
|
|
| `/api/v1/storage/snapshots` | `GET`, `POST` | Snapshot creation and instant rollback |
|
|
| `/api/v1/shares/smb` | `GET`, `POST` | Samba shares and Time Machine configurations |
|
|
| `/api/v1/shares/nfs` | `GET`, `POST` | NFS exports and CIDR rules |
|
|
| `/api/v1/apps/catalog` | `GET` | Catalog of deployable applications |
|
|
| `/api/v1/apps/installed` | `GET`, `POST` | Install and manage active app workloads |
|
|
| `/api/v1/gitops/status` | `GET` | Remote synchronization and commit state |
|
|
| `/api/v1/gitops/rollback` | `POST` | Instant rollback to arbitrary commit SHA |
|
|
| `/api/v1/logs/stream` | `GET` | Real-time Server-Sent Events journald stream |
|
|
|
|
## Development & Testing
|
|
|
|
```bash
|
|
npm install
|
|
npm test
|
|
npm run build
|
|
npm start
|
|
``` |