38 lines
2.0 KiB
Markdown
38 lines
2.0 KiB
Markdown
# 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.
|