50 lines
3.1 KiB
Markdown
50 lines
3.1 KiB
Markdown
# NaxOS Management Daemon & API (`naxos-api`)
|
|
|
|
[](https://git.lholz.de/naxos/naxos-api/actions)
|
|
|
|
The **NaxOS Management Daemon** serves as the core orchestration brain of the NaxOS storage appliance. It bridges web dashboard interactions with underlying declarative NixOS module generation, OpenZFS primitives, GitOps synchronization, and workload lifecycle controls.
|
|
|
|
## Appliance Interface Showcase
|
|
|
|
| Overview & Telemetry | OpenZFS Storage Engine |
|
|
| :---: | :---: |
|
|
|  |  |
|
|
| **CNCF Perses Analytics** | **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.
|
|
- **Native Perses Analytics & SSE Logs**: Serves embedded Perses dashboard configurations 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
|
|
``` |