docs: complete NaxOS architectural specs, migration guides, API reference, and CI workflows

2026-09-04 00:15:21 +02:00
parent 2719f87e9e
commit ce7c125391
11 changed files with 490 additions and 2 deletions
@@ -0,0 +1,95 @@
+# NaxOS Management Daemon REST & WebSocket API Reference
+
+The NaxOS daemon listens on internal port `8088` (reverse-proxied via Nginx on port `80`/`443` at `/api/`).
+
+---
+
+## 1. System & Engine
+
+### `GET /api/v1/system/status`
+Returns high-level appliance status, health metrics, and active generation.
+
+**Response Example**:
+```json
+{
+  "status": {
+    "hostname": "naxos",
+    "uptimeSeconds": 864200,
+    "cpuUsagePercent": 12.4,
+    "memoryTotalBytes": 33554432000,
+    "memoryUsedBytes": 14200000000,
+    "arcSizeBytes": 4294967296,
+    "arcHitRatioPercent": 98.6,
+    "zfsPoolsCount": 1,
+    "activeSharesCount": 3,
+    "runningAppsCount": 2,
+    "osVersion": "NaxOS 24.11 (NixOS Vicuna)",
+    "nixosGeneration": 42
+  }
+}
+```
+
+### `POST /api/v1/system/rebuild`
+Triggers `nixos-rebuild-safe` and streams stdout/stderr output in real-time as **Server-Sent Events (SSE)** (`text/event-stream`).
+
+---
+
+## 2. OpenZFS Storage
+
+### `GET /api/v1/storage/pools`
+Lists all active OpenZFS pools, capacity, fragmentation, and health.
+
+### `POST /api/v1/storage/pools`
+Creates a new OpenZFS pool.
+**Payload**:
+```json
+{
+  "name": "tank",
+  "layout": "mirror",
+  "devices": ["/dev/sda", "/dev/sdb"],
+  "ashift": 12
+}
+```
+
+### `GET /api/v1/storage/unimported`
+Scans connected disks for foreign pools (TrueNAS / legacy NixOS) available for zero-data-loss import.
+
+### `POST /api/v1/storage/import`
+Safely imports a pool.
+**Payload**:
+```json
+{
+  "poolName": "tank",
+  "force": true,
+  "noMount": true
+}
+```
+
+### `GET /api/v1/storage/datasets`
+Lists datasets, compression, mountpoint, and quotas.
+
+---
+
+## 3. GitOps Synchronization
+
+### `GET /api/v1/gitops/status`
+Returns current branch, head commit SHA, and remote sync state.
+
+### `GET /api/v1/gitops/commits`
+Returns generation commit history log.
+
+### `POST /api/v1/gitops/rollback`
+Instantly rolls back the declarative appliance configuration to the specified Git commit hash.
+**Payload**:
+```json
+{
+  "commitSha": "5da58ae0912f1"
+}
+```
+
+---
+
+## 4. Real-Time Logs
+
+### `GET /api/v1/logs/stream`
+SSE stream delivering journald logs in real time. Supports optional `?unit=<service>` query parameter.
@@ -0,0 +1,46 @@
+# NaxOS Developer & Contribution Guide
+
+## Repository Structure under `naxos` Organization
+
+The NaxOS ecosystem is structured across dedicated repositories on Gitea (`git.lholz.de/naxos`):
+
+1. **`naxos-os`**: The core NixOS distribution flake, modules, profiles, and bootable ISO installer.
+2. **`naxos-api`**: The TypeScript management daemon, ZFS driver, GitOps engine, and unit tests.
+3. **`naxos-ui`**: The React 18, Tailwind CSS, and CNCF Perses web dashboard.
+4. **`naxos-docs`**: Architectural blueprints, end-user tutorials, and migration guides.
+
+---
+
+## Local Development Workflow
+
+### Developing `naxos-api`
+```bash
+cd naxos-api
+npm install
+npm test          # Run Vitest test suite
+npm run dev       # Watch mode on port 8088
+```
+
+### Developing `naxos-ui`
+```bash
+cd naxos-ui
+npm install
+npm run dev       # Vite development server on port 3000
+npm run build     # Production compile
+```
+
+### Testing NixOS Modules in `naxos-os`
+```bash
+cd naxos-os
+nix flake check
+nix eval .#nixosConfigurations.naxos.config.system.build.toplevel.drvPath
+```
+
+---
+
+## Gitea Actions CI/CD Workflows
+Each repository includes automated Gitea Actions workflows in `.gitea/workflows/`:
+- **`naxos-os`**: Automated ISO build, flake check, and release artifact generation.
+- **`naxos-api`**: Automated lint, typecheck, and unit testing.
+- **`naxos-ui`**: Automated frontend build and artifact packaging.
+- **`naxos-docs`**: Documentation validation.