naxos-api/README.md

NaxOS Management Daemon & API (naxos-api)

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

npm install
npm test
npm run build
npm start