System-level architecture for the Smooth* family — four Debian-based appliance OSes built on a shared foundation. This doc lives in smoothkernel because the kernel is the piece every flavor shares; companion docs in this directory cover the apt repo, graphics stack, per-flavor specs, installer framework, and release model.
| Flavor | What it is | Shell / surface |
|---|---|---|
| SmoothNAS | Linux storage appliance (mdadm + LVM + ZFS + SMB/NFS/iSCSI) | Headless, web UI |
| SmoothRouter | Linux router (nftables + unbound + Kea + wireguard) | Headless, web UI |
| SmoothHTPC | HTPC kiosk (boot-to-custom-shell fronting Kodi + emulators) | smoothtv shell (Tauri) |
| SmoothDesktop | Windows-replacement desktop | KDE Plasma 6 + smoothdesktop-theme |
All four run on the same base Debian, the same kernel line, the same apt repo. The deltas are userspace.
flowchart TD
DebianBase["Debian trixie (stable)"]
SmoothKernel["linux-smoothkernel (.deb)"]
SmoothBase["smooth-base (keyring, apt source, pinning, shared scripts)"]
SmoothFirmware["linux-firmware-smooth"]
SmoothMesa["mesa (RakuenSoftware rebuild)"]
SmoothGfx["smooth-gfx (Mesa + firmware + drivers)"]
SmoothWorkstation["smooth-workstation (smooth-gfx + PipeWire + NM + bluez + Flatpak + codecs)"]
Nas["smoothnas"]
Router["smoothrouter"]
Htpc["smoothhtpc"]
Desktop["smoothdesktop"]
DebianBase --> SmoothKernel
DebianBase --> SmoothBase
DebianBase --> SmoothFirmware
DebianBase --> SmoothMesa
SmoothMesa --> SmoothGfx
SmoothFirmware --> SmoothGfx
SmoothGfx --> SmoothWorkstation
SmoothKernel --> Nas
SmoothKernel --> Router
SmoothKernel --> Htpc
SmoothKernel --> Desktop
SmoothBase --> Nas
SmoothBase --> Router
SmoothBase --> Htpc
SmoothBase --> Desktop
SmoothFirmware --> Nas
SmoothFirmware --> Router
SmoothWorkstation --> Htpc
SmoothWorkstation --> Desktop
Everything above the flavor row is shared. Only the flavor row diverges.
Debian trixie (Debian 13) as the base for every flavor. Reasons:
- SmoothNAS already ships a custom Debian installer in
iso/. Ubuntu would orphan that work. - Debian has cleaner defaults for appliance shipping (no snap pushes, no non-free bundled in ways that complicate licensing).
- The usual "Ubuntu HWE" argument for fresher kernel + Mesa + firmware is moot:
linux-smoothkernel,mesa(rebuilt), andlinux-firmware-smoothreplace exactly what HWE updates — and do it more aggressively.
non-free-firmware is a first-class component under Debian 12+. Installers enable it; smooth-base's postinst does the same on existing systems.
linux-smoothkernel is one shared kernel line installed by every flavor. It is built per Debian architecture (amd64, arm64), but not per OS flavor.
The flavor-level differences that people intuitively associate with "server vs desktop kernels" are almost entirely userspace-tunable:
- I/O scheduler selection → udev rules per flavor
- VM and network sysctls →
/etc/sysctl.d/fragments per flavor - CPU governor defaults → tuned profiles per flavor
Compile-time choices that can't move to userspace (CONFIG_PREEMPT, CONFIG_HZ) are locked to values that work everywhere with BORE:
CONFIG_PREEMPT=y— full preemption. The throughput cost on I/O-bound NAS workloads is in the noise on modern hardware with BORE.CONFIG_HZ=1000— latency responsiveness. Negligible server impact.
This collapses kernel maintenance from four flavor pipelines to one source/patch/config policy with per-architecture build artifacts. See KERNEL.md.
CachyOS publishes a clean, versioned patch series at github.com/CachyOS/kernel-patches designed for downstream reuse. Its patchset (BORE, BBRv3, MM tuning, sched-ext, filesystem improvements) is a strict improvement over mainline for every Smooth* flavor — explicitly including headless NAS and router workloads.
Nobara's patches are entangled with Fedora SRPM build scripts; its HID/controller/OpenRGB bits are worth cherry-picking on top of CachyOS, and they have zero cost on headless systems (drivers only load with the hardware).
See KERNEL.md for the patch intake process.
One scheduler, not a family. CachyOS offers BORE, sched-ext, EEVDF-tuned, and hardened variants; Smooth* picks BORE only. Reasons:
- Burst-aware behavior suits every flavor (Samba many-client, nftables under load, game input, UI responsiveness).
- Single default means predictable support surface.
- sched-ext support still compiled in for advanced users, just not the default.
The per-flavor -tuning packages (smoothnas-tuning, smoothrouter-tuning, etc.) ship only:
- udev rules (I/O scheduler)
- sysctl fragments (network buffers, VM, forwarding, etc.)
- tuned profile (CPU governor)
They're deliberately trivial and independently installable. Someone could put smoothrouter-tuning on a bare Debian and get the networking sysctls without any of the router-specific daemons.
HTPC gets a custom shell because no good OSS HTPC launcher exists as a coherent product — Kodi's UI is Kodi-specific; Plasma Bigscreen is tied to Plasma. smoothtv is a Tauri app built on @rakuensoftware/smoothgui that runs inside a wlroots kiosk compositor and launches Kodi / Steam Big Picture / RetroArch as sibling children. Steam Deck / SteamOS pattern.
Desktop does not get a custom shell. KDE Plasma 6 is flexible enough that a config-only theme package (smoothdesktop-theme) gets 90% of the "polished Windows replacement" feel for maybe 2% of the effort of a custom shell. Save the custom-shell budget for HTPC where it's actually justified.
See SMOOTHHTPC.md and SMOOTHDESKTOP.md.
The existing apt repo uses one apt suite per product (smoothnas, smoothrouter). That's a good shape; extend it with a common suite for cross-product packages (linux-smoothkernel, mesa, linux-firmware-smooth, smooth-base, smooth-workstation, smoothgui-assets).
Every flavor's sources.list enables its product suite plus common:
deb <url> common main
deb <url> smoothnas main
See APT_REPO.md.
Debian stable is a feature for 80% of the stack — Samba, NFS, nftables, unbound, Kea, PipeWire, WirePlumber, nginx, systemd, Go/Node toolchains. Ship those as-is.
Override where Debian's freeze hurts:
| Package | Override? | Why |
|---|---|---|
linux-smoothkernel |
Always | Kernel is the centerpiece; on CachyOS cadence |
mesa |
Always | Debian stable's Mesa lags by a year+; unacceptable for HTPC/desktop GPU features and video decode |
linux-firmware-smooth |
Always | New GPUs need firmware blobs Debian hasn't shipped |
kodi |
Probably | Yearly upstream cadence; HTPC UX regresses on stale versions |
llvm |
Only when forced | Debian 13 ships LLVM 19, enough through most of 2025 |
kde-plasma-* |
Only if stable feels too stale | Re-evaluate at ship time |
| Everything else | No | Debian stable is the right posture |
See RELEASE_MODEL.md for cadence and promotion.
Engineering investment, largest first:
- smoothkernel — perpetual rebase on CachyOS cadence
- smoothtv — greenfield Tauri product + session plumbing
- mesa — quarterly rebuild, occasional LLVM pain
- smoothnas debian/ packaging — wrap existing Makefile, produce .debs
- smoothrouter backend + UI — greenfield but scope-contained
- Shared installer extraction from
SmoothNAS/iso/ - smoothdesktop-theme — config files only
- Meta + tuning packages — trivial
- Not a distro in the "new Linux from scratch" sense. It's Debian with an overlay of the specific packages Debian stable under-serves.
- Not a general-purpose desktop distro competing with Ubuntu/Fedora/etc. Each flavor is opinionated for its role.
- Not trying to absorb or replace enterprise products (TrueNAS Enterprise, pfSense Plus, Bazzite). Scope is homelab / workstation / small office.
- Stable channel model. Start with a single
maincomponent per suite; addtestingfor pre-promotion soak once rebase cadence justifies it. - Module signing and Secure Boot. Standardized in
signing.md: release-built modules must be signed by the signing-capable release path, and DKMS modules are signed on-host viasmooth-secureboot. - Arm64 hardware scope. Arm64 packages are first-class, but board enablement still needs real target validation. UEFI/SBSA systems are the easiest support lane; SBC-style devices may need firmware and bootloader work outside smoothkernel.