# NaxOS Management Daemon & API (`naxos-api`)

[![Gitea Actions](https://git.lholz.de/naxos/naxos-api/actions/workflows/ci.yaml/badge.svg)](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 |
| :---: | :---: |
| ![Dashboard Overview](docs/images/dashboard-overview.png) | ![Storage Management](docs/images/storage-management.png) |
| **CNCF Perses Analytics** | **App Store & Runtimes** |
| ![Perses Analytics](docs/images/perses-analytics.png) | ![App Store](docs/images/app-store.png) |

## 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
```