ONYX — Design Documents¶
ONYX (Online Storage System — Platform) is an open-source storage and infrastructure platform that replaces TrueNAS and ZimaOS: enterprise-grade storage, virtualization, object storage, backup management, cloud synchronization, and application hosting — private and self-hosted, with a modern app feel rather than an enterprise appliance.
These documents are the living specification for the project. They are written to be read in order, but each stands alone and is versioned independently so teams can evolve areas at their own pace.
| # | Document | What it covers |
|---|---|---|
| 01 | Product Vision | Why Onyx exists, who it's for, positioning vs. competitors, principles, roadmap |
| 02 | Technical Architecture | System layers, stack decisions, module map, data flow, performance budgets |
| 03 | Frontend Design System | "Prism" design language, tokens, components, file explorer UX, a11y |
| 04 | Backend Service Architecture | Service inventory, IPC, config/state layout, privilege model, observability |
| 05 | Storage Subsystem | Btrfs pools, subvolume layout, snapshots, quotas, scrub, sharing protocols |
| 06 | API Specification | REST + WebSocket conventions, endpoint catalog, error model, versioning |
| 07 | Security Model | Threat model, trust boundaries, sandboxing, auth flows, audit, supply chain |
| 08 | User Management | Users, groups, roles, ACLs, quotas, API keys, OIDC/LDAP/AD integration |
| 09 | App Ecosystem | App format, store, install UX, sandboxing, SDK, curated catalog |
| 10 | Installer and Updates | Installation targets, first-boot wizard, ostree A/B updates, rollback |
| 11 | Platform and Cloud | Authentik SSO, Nginx Proxy Manager + TSIG wildcard certs, subdomain routing, Dockerized deployment, virtualization, container management, AI Storage Advisor, object storage + hybrid cloud, release pipeline |
Status¶
- Phase: Design — all documents are drafts to be validated with prototype builds.
- Canonical source of truth: this directory. Code comments must reference document sections
(
docs/design/05#snapshots) when they encode a design decision. - RFC process: any change to a numbered section ships as an RFC in
docs/rfcs/before merge.
Decisions log (TL;DR)¶
The single most important decisions, in one place:
| Decision | Choice | Rationale |
|---|---|---|
| Base OS | Minimal Debian (Trixie) | Predictable tooling, huge package surface, long-term support |
| Root filesystem | OSTree-managed, read-only, A/B | Atomic updates, rollback, tamper resistance |
| Primary filesystem | Btrfs | Snapshots, checksums, compression, quotas at low RAM cost vs. ZFS |
| System language | Rust (data plane), Go (control plane) | Rust for FS-level safety, Go for fast, safe API/orchestration code |
| Frontend | TypeScript + React SPA, "Prism" design system | Fast iteration, rich UX; served from the gateway |
| Apps | Docker containers + Compose, AppArmor/seccomp | Largest ecosystem, familiar to maintainers |
| System DB | SQLite (WAL) per service | Zero-administration, transactional, no separate server |
| Auth | Authentik (OIDC/SSO) as the platform IdP; local accounts + TOTP/WebAuthn fallback | Every service signs in through auth.onyx.innotel.us |
| Reverse proxy | Nginx Proxy Manager, provisioned via API | TLS termination, wildcard *.onyx.innotel.us via TSIG DNS-01, six subdomains |
| License | AGPL-3.0 core, Apache-2.0 SDKs/app SDK | Keeps the core free, encourages app ecosystem |