naxos-os/README.md

NaxOS Core (naxos-os)

NaxOS is a declarative, appliance-like Network Attached Storage (NAS) operating system built on top of NixOS and OpenZFS.

Appliance Interface Preview

Overview Dashboard	OpenZFS Storage Engine
CNCF Perses Analytics	App Store & Runtime

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

nix build .#iso

Testing System Evaluation

nix flake check
nix eval .#nixosConfigurations.naxos.config.system.build.toplevel.drvPath