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,37 @@
+# Declarative Backend & GitOps Synchronization Engine
+
+## Core Workflow
+
+NaxOS eliminates drift between what the Web Dashboard displays and what the underlying operating system executes.
+
+When an administrator performs an action in the UI (e.g. creating a share, setting a dataset quota, installing Immich):
+
+1. **REST API Request**: The frontend sends a strongly typed JSON payload to the NaxOS Management Daemon (`naxos-api`).
+2. **In-Memory & JSON State Update**: The daemon validates the payload against its schemas and updates `/etc/naxos/repo/naxos-config.json`.
+3. **NixOS Code Generation**: The daemon's compiler generates `/etc/naxos/repo/generated-naxos-config.nix`.
+4. **Git Transaction**:
+   - The daemon commits the modified files into the local Git repository at `/etc/naxos/repo`.
+   - If a remote repository is configured (e.g. on Gitea), it pushes the commit automatically to `origin/main`.
+5. **Dry-Run Validation**:
+   - Before any running service is altered, `naxos-rebuild-safe` performs a dry build:
+     ```bash
+     nixos-rebuild build --flake .#naxos
+     ```
+   - If evaluation or build fails (e.g. invalid option syntax or dependency conflict), the transaction is immediately aborted and the running system remains untouched.
+6. **Atomic Switch & Canary Verification**:
+   - The new generation is activated using `nixos-rebuild switch`.
+   - The canary runner tests daemon connectivity and storage accessibility.
+   - If canary verification fails, the system automatically runs:
+     ```bash
+     "$PREV_GEN/bin/switch-to-configuration" switch
+     ```
+   - The user is alerted in the dashboard with full build logs.
+
+---
+
+## 1-Click Rollback Mechanism
+
+Because every generation is tied to an explicit Git commit and NixOS system profile generation:
+- The user can browse the commit history in the Web UI.
+- Clicking **Rollback** checks out the selected commit and activates the previous generation in seconds.
+- No database dumps or manual backups are needed for appliance recovery.