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,19 @@
+# App Engine & Workload Runtime Architecture
+
+NaxOS features a tri-tier runtime engine that selects the best execution strategy for each application:
+
+## 1. Native NixOS Systemd Services
+- **Best For**: High-throughput services requiring direct hardware device passthrough, minimal RAM overhead, and deep integration with OpenZFS.
+- **Example**: **Immich** Photo Hub.
+  - Native Nixpkgs package running as an isolated systemd service.
+  - Direct Intel QuickSync (`/dev/dri/renderD128`) access with `extraPackages = [ intel-media-driver intel-compute-runtime vpl-gpu-rt ]`.
+  - Native systemd CPU quota: `CPUQuota = "200%"` to avoid choking the storage daemon during intensive facial recognition or CLIP embedding indexing.
+  - Photos stored directly in OpenZFS dataset `/tank/media/photos`.
+
+## 2. Rootless Docker / Compose Engine
+- **Best For**: General third-party containerized workloads.
+- **Backend**: Configured with Docker's native `zfs` storage driver (`virtualisation.docker.storageDriver = "zfs"`). Container image layers become native ZFS subvolumes with instant snapshots and copy-on-write deduplication.
+
+## 3. Lightweight K3s
+- **Best For**: Cloud-native Helm charts and multi-service distributed workloads.
+- Can be activated on demand via `services.naxos.appEngine.k3s.enable = true`.