# NaxOS Core (`naxos-os`)

[![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**.

## Appliance Interface Preview

| Overview Dashboard | OpenZFS Storage Engine |
| :---: | :---: |
| ![Dashboard Overview](docs/images/dashboard-overview.png) | ![Storage Management](docs/images/storage-management.png) |
| **CNCF Perses Analytics** | **App Store & Runtime** |
| ![Perses Analytics](docs/images/perses-analytics.png) | ![App Store](docs/images/app-store.png) |

## 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
```