diff --git a/context/dev-standards.md b/context/dev-standards.md new file mode 100644 index 0000000..697b81f --- /dev/null +++ b/context/dev-standards.md @@ -0,0 +1,229 @@ +# NixOS Repo Notes (atlas/server/laptop) + +This document summarizes the current NixOS configuration repo layout, patterns, and +modules as implemented in `flake.nix`, `hosts/**/configuration.nix`, and `modules/**.nix`. + +## Setup Details (What This Config Builds) + +- Flake-based multi-host NixOS: `atlas` (desktop), `laptop` (desktop no gaming), `server` + (headless). See `flake.nix` and `hosts/README.md`. +- Channel: `nixos-unstable` via `inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";` + in `flake.nix`. +- Kernel: CachyOS kernel via `nix-cachyos-kernel` overlay added in `flake.nix` modules list. + - Desktop uses `pkgs.cachyosKernels.linuxPackages-cachyos-latest-x86_64-v3` in + `modules/core/boot.nix`. + - Server uses `pkgs.cachyosKernels.linuxPackages-cachyos-server` in + `modules/core/boot_server.nix`. +- Bootloader: Limine with Secure Boot enabled. + - `boot.loader.limine.enable = true;` + - `boot.loader.limine.secureBoot.enable = true;` + - Wallpaper set to `wallpaper/nix.png`. +- Disk encryption (atlas hardware config currently checked in): + - Root: LUKS2 `cryptroot` mapped to `/dev/mapper/cryptroot` with XFS (`hosts/atlas/hardware-configuration.nix`). + - Swap: LUKS2 `cryptswap` with keyfile at `/var/lib/secrets/swap.key` included in initrd. + - `boot.resumeDevice = "/dev/mapper/cryptswap";` in `modules/core/boot.nix`. +- Boot UX and kernel params: + - Plymouth enabled (`nixos-bgrt`) and `quiet/splash/loglevel` tuned in `modules/core/boot.nix`. + - `boot.initrd.systemd.enable = true;`. +- Scheduler tuning: `services.scx.enable = true; services.scx.scheduler = "scx_lavd";` + in `modules/core/boot.nix` (and `modules/core/boot_server.nix`). +- Nix settings: + - `nix-command` + `flakes` enabled in `modules/core/system.nix`. + - Unfree allowed: `nixpkgs.config.allowUnfree = true;`. + - Auto upgrade weekly + GC daily (delete older than 10d) in `modules/core/system.nix`. + - `system.stateVersion = "26.05";`. +- Networking defaults (core module): + - `networking.networkmanager.enable = true;` + - `services.openssh.enable = true;` + - `services.tailscale.enable = true;` + - `networking.hostName = "nix";` (see “Notable Repo Quirks” below). +- Locale: + - Timezone `Europe/Berlin` + - Default locale `en_US.UTF-8` with many `de_DE.UTF-8` `LC_*` overrides + - Console keymap `de-latin1-nodeadkeys` +- Desktop stack (atlas/laptop): + - Display manager: `ly` via `services.displayManager.ly.enable = true;` + - Session: `services.displayManager.defaultSession = "niri";` + - WM/Compositor: `programs.niri.enable = true;` (`modules/desktop/niri.nix`) + - XDG portals: enabled with GTK portal + polkit agent user service +- Audio: PipeWire + WirePlumber, Bluetooth enabled; Pulseaudio disabled. +- Flatpak: enabled and adds Flathub remote during activation. +- Gaming (atlas): + - Steam with firewall openings and Proton GE. + - GameMode with sysctl tuning and `gamescope`. + - Wine staging + udev rules for game devices. +- Dev tooling: + - Docker enabled with weekly auto prune. + - `direnv` + `nix-direnv` enabled. + - Large CLI/dev package set including `nixd`, `nil`, `nixfmt`, `claude-code`, and `opencode`. + +## Repository Structure and Import Graph + +- Host entrypoints are under `hosts//configuration.nix`: + - `hosts/atlas/configuration.nix` imports: + - `./hardware-configuration.nix` + - `../../modules/core` + - `../../modules/hardware` + - `../../modules/desktop` + - `../../modules/services` + - `../../modules/dev` + - `../../modules/gaming` + - `hosts/laptop/configuration.nix` imports: + - core/hardware/desktop/dev plus a subset of services modules + - `hosts/server/configuration.nix` imports: + - specific core/hardware modules + `../../modules/dev` + `../../modules/services/maintenance.nix` + - enables `services.openssh.enable = true;` explicitly (core also enables it) + +### Flake Outputs and Host Construction + +`flake.nix` defines: + +- `specialArgs = { inherit inputs username; };` so modules can reference: + - `username` for user paths (e.g. `users.users.${username}`; `MusicFolder = "/home/${username}/Music"`). + - `inputs` for flake packages (e.g. Zen browser, Noctalia shell, Opencode). +- A helper `mkHost hostname = nixpkgs.lib.nixosSystem { ... }` that loads: + - `./hosts/${hostname}/configuration.nix` + - an inline module setting `nixpkgs.overlays = [ inputs.nix-cachyos-kernel.overlays.pinned ];` +- `nixConfig` binary caches: + - `nix-community` Cachix + - `attic.xuyh0120.win/lantian` + +### Module Categories + +`modules/default.nix` aggregates: + +- `modules/core/default.nix` +- `modules/hardware/default.nix` +- `modules/desktop/default.nix` +- `modules/services/default.nix` +- `modules/dev/default.nix` +- `modules/gaming/default.nix` + +Each category `default.nix` is “imports only” style. + +## Configuration Patterns Used + +- **Module function signature**: + - Most modules follow `{ config, pkgs, lib, ... }:` plus `inputs` and/or `username` when needed. +- **Centralized username**: + - `flake.nix` sets `username = "pinj";` and passes it via `specialArgs`. +- **Accessing packages from flake inputs**: + - Pattern used in `modules/desktop/apps.nix` and `modules/dev/tools.nix`: + - `inputs..packages.${pkgs.stdenv.hostPlatform.system}.default` +- **Overlays**: + - Global CachyOS kernel overlay is injected from `flake.nix`. + - Dev category also adds a local overlay: + - `modules/dev/default.nix` sets `nixpkgs.overlays = [ (import ../../overlays/firebase-tools.nix) ];` + - `overlays/firebase-tools.nix` forces `firebase-tools` to use `nodejs_22` when available. +- **System packages as the main mechanism**: + - Many features are enabled by adding to `environment.systemPackages` in the relevant module. +- **Host-specific composition**: + - “Desktop features” are composed by importing modules; server imports a smaller subset. + +## Modules Used (By Category) + +### Core (`modules/core/*`) + +- `modules/core/boot.nix` + - Limine boot + Secure Boot, kernel selection, Plymouth, kernel params + - scx scheduler configuration +- `modules/core/boot_server.nix` + - Same structure as `boot.nix` but uses `linuxPackages-cachyos-server` +- `modules/core/system.nix` + - Nix flakes enablement, auto upgrade, GC, allowUnfree, `system.stateVersion` +- `modules/core/networking.nix` + - NetworkManager, OpenSSH, Tailscale, default hostname +- `modules/core/users.nix` + - Creates `users.users.${username}` with Fish shell and group memberships + - Enables Fish and Zsh +- `modules/core/localization.nix` + - Timezone/locale and console keymap + +### Hardware (`modules/hardware/*`) + +- `modules/hardware/storage.nix` + - Mount points for several ext4 SSDs under `/mnt/*` with `nofail` and GVFS visibility + - Weekly fstrim + - zram swap enabled (`memoryPercent = 100`, `algorithm = "zstd"`) +- `modules/hardware/audio.nix` + - PipeWire + WirePlumber config, 32-bit ALSA support, Bluetooth enabled + - Adds audio utilities (`pavucontrol`, `pwvucontrol`, `playerctl`) +- `modules/hardware/gpu-amd.nix` + - AMD graphics stack, 32-bit support, VA-API/VDPAU helpers, ROCm ICD + - CoreCtrl + AMD overdrive +- `modules/hardware/power.nix` + - power-profiles-daemon + CPU governor + +### Desktop (`modules/desktop/*`) + +- `modules/desktop/niri.nix` + - Enables X server, `ly` display manager, default session `niri`, XKB layout +- `modules/desktop/portals.nix` + - XDG portal (GTK), polkit enabled + user `polkit-gnome-agent` systemd service + - Wayland-related env vars and utilities +- `modules/desktop/theming.nix` + - Font packages + fontconfig defaults, gtk/qt theming utilities +- `modules/desktop/apps.nix` + - GUI app set + - Installs Zen browser via flake input + - Installs Noctalia shell via flake input + - Enables Flatpak + adds Flathub remote in activation script + - Enables GNOME keyring, `programs.yazi`, and `programs.firefox` + +### Services (`modules/services/*`) + +- `modules/services/avahi.nix` + - Avahi mDNS publishing + firewall openings +- `modules/services/printing.nix` + - CUPS printing +- `modules/services/maintenance.nix` + - `psd`, `fwupd`, `earlyoom`, `plocate` periodic indexing +- `modules/services/navidrome.nix` + - Local-only Navidrome on `127.0.0.1:4533` with `MusicFolder=/home/${username}/Music` + - Ensures `~/Music` exists via tmpfiles + +### Development (`modules/dev/*`) + +- `modules/dev/docker.nix` + - Docker enabled + weekly auto prune; includes `docker-compose` and `lazydocker` +- `modules/dev/shell.nix` + - Fish prompt and shell init (Ghostty integration if present), lots of aliases/abbrs + - Fish plugins and CLI QoL tools +- `modules/dev/tools.nix` + - Toolchains and CLIs (node/python/rustup, compilers, nix tooling, cloud CLIs, AI tools) + - Installs Opencode via flake input + +### Gaming (`modules/gaming/*`) + +- `modules/gaming/steam.nix` + - Steam enabled, firewall exceptions, Proton GE, steam hardware udev rules +- `modules/gaming/gamemode.nix` + - GameMode enabled with renice + AMD perf-level config + - Sysctl tuning for gaming workloads + - Includes `gamemode` and `gamescope` +- `modules/gaming/wine.nix` + - Wine staging + helpers; controller udev rules + +## Operational Commands (Repo-Local) + +- Evaluate and validate: + - `nix flake check` +- Build without activating: + - `sudo nixos-rebuild dry-build --flake .#atlas` + - `sudo nixos-rebuild dry-build --flake .#laptop` + - `sudo nixos-rebuild dry-build --flake .#server` +- Activate (on target machine): + - `sudo nixos-rebuild switch --flake .#atlas` (or `#laptop`, `#server`) +- Format: + - `nixfmt **/*.nix` + +## Notable Repo Quirks / Potential Follow-Ups + +- `modules/core/networking.nix` sets `networking.hostName = "nix";` which will apply to all + hosts unless overridden elsewhere (host configs currently comment about setting hostname). +- `scripts/setup-secureboot.sh` and `scripts/install-fde.sh` reference `#nixos` in their + example commands, but `flake.nix` defines `#atlas`, `#server`, and `#laptop`. +- `modules/core/boot_server.nix` file header comment says `modules/core/boot.nix` (cosmetic). +- `hosts/server/hardware-configuration.nix` and `hosts/laptop/hardware-configuration.nix` + are identical to `hosts/atlas/hardware-configuration.nix` in this repo snapshot (likely placeholders). +