feat(core): initialize NaxOS declarative NixOS distribution, modules, and ISO installer

2026-09-03 23:53:18 +02:00
parent 88a638955b
commit 5da58ae6d7
28 changed files with 2247 additions and 2 deletions
@@ -1,3 +1,58 @@
-# naxos-os
+# NaxOS Core (`naxos-os`)

-NaxOS Operating System - Declarative NixOS Core, Modules, ISO Installer, and Appliance Architecture
+[![Gitea Actions](https://git.lholz.de/naxos/naxos-os/actions/workflows/test-modules.yaml/badge.svg)](https://git.lholz.de/naxos/naxos-os/actions)
+
+**NaxOS** is a declarative, appliance-like Network Attached Storage (NAS) operating system built on top of **NixOS** and **OpenZFS**.
+
+## Architecture & Features
+
+- **Declarative NixOS Foundation**: Complete system state defined as code, from kernel sysctl parameters to users and storage configurations.
+- **GitOps-Driven Rebuilds**: Automated `nixos-rebuild switch` with dry-build safety checks, canary testing, and instant rollback.
+- **Native OpenZFS Management**:
+  - Declarative pools (mirror, raidz1, raidz2, stripe)
+  - Declarative datasets with per-dataset quotas, compression (`lz4`, `zstd`), and recordsize tuning
+  - First-class zero-data-loss import of existing pools (e.g. from TrueNAS or raw NixOS setups like `nixos-lukas`)
+  - Automated scrub, TRIM, and snapshot lifecycle policies (hourly, daily, weekly, monthly)
+- **Multi-Protocol File Shares**:
+  - **Samba**: Preconfigured with macOS Time Machine support (`vfs_fruit`), POSIX ACL propagation, and fine-grained share permissions.
+  - **NFS**: High-throughput NFS exports with CIDR client filters.
+- **Multi-Tier Workload & App Engine**:
+  - Native NixOS systemd services (e.g. Immich with Intel QuickSync / OpenCL hardware transcoding)
+  - Docker Compose with ZFS copy-on-write storage driver
+  - Optional lightweight K3s cluster integration
+- **Native Observability**:
+  - Embedded **Perses** analytics dashboards (replacing standalone Grafana)
+  - Prometheus TSDB and Node Exporter
+- **Streamlined Bootable ISO**:
+  - Interactive CLI / TUI wizard (`naxos-installer`) for rapid bare-metal installation and pool import.
+
+## Repository Structure
+
+```
+naxos-os/
+├── flake.nix                   # Flake exports (modules, configurations, ISO builder)
+├── modules/                    # NaxOS module definitions
+│   ├── core/                   # System base, users, gitops, self-update
+│   ├── storage/                # ZFS pool/dataset management & migration
+│   ├── shares/                 # Samba (SMB) and NFS file shares
+│   ├── services/               # App engine runtime & application catalog
+│   ├── monitoring/             # Prometheus & Perses analytics engine
+│   ├── api/                    # Management daemon systemd service
+│   └── ui/                     # Web dashboard Nginx reverse proxy service
+├── profiles/                   # Hardware & appliance base profiles
+├── iso/                        # Bootable installer ISO & scripts
+└── .gitea/workflows/           # Gitea Actions CI/CD workflows
+```
+
+## Quick Start
+
+### Building the Installation ISO
+```bash
+nix build .#iso
+```
+
+### Testing System Evaluation
+```bash
+nix flake check
+nix eval .#nixosConfigurations.naxos.config.system.build.toplevel.drvPath
+```