ragusa-it/nixos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
09834f2531a24143b255eecff8e842ada35c1a6f
nixos/context/dev-standards.md
Melvin Ragusa 09834f2531 docs: add dev standards from repo analysis 
- NixOS flake config for atlas/server/laptop
- Module categories and patterns
- Boot, desktop, gaming, dev tooling setup
2026-02-14 09:07:32 +00:00

9.9 KiB
Raw Blame History

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/<hostname>/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.<name>.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).
Reference in New Issue View Git Blame Copy Permalink