NixOS/docs/reference/index.md

Reference Map

Module Directories

• apps → modules/apps/ (desktop/workstation apps; supports legacy flat modules and preferred split feature directories)
• dev → modules/dev/ (language toolchains and dev shells; supports legacy flat modules and preferred split feature directories)
• scripts → modules/scripts/ (script units built via mkscript; supports legacy flat modules and preferred split feature directories)
• servers → modules/servers/ (reverse-proxied services built via mkserver; supports legacy flat modules and preferred split feature directories)
• services → modules/services/ (supporting services like syncthing, wireguard; supports legacy flat modules and preferred split feature directories)
• shell → modules/shell/ (shell customizations and CLI tooling; supports legacy flat modules and preferred split feature directories)
• websites → modules/websites/ (static nginx vhosts for portfolio/blog and reports; supports legacy flat modules and preferred split feature directories)
• network → modules/network/ (networking rules, firewall helpers; supports legacy flat modules and preferred split feature directories)
• users → modules/users/ (user-related options)
• nix → modules/nix/ (Nix configuration and helpers)
• factories → modules/factories/ (mkserver.nix, mkscript.nix shared helpers)
• home-manager loader → modules/home-manager.nix (discovers nested home.nix files under modules/)

Root Directories

• patches → patches/ (patch artifacts referenced by modules)

User Config Split

• System-side user config: config/<name>.nix for NixOS user accounts, host secrets, groups, and other OS-owned state.
• Home-side user config: config/<name>-home.nix for Home Manager-only files, shell/program configuration, and per-user match blocks.
• Current example: config/jawz.nix and config/jawz-home.nix.

Auto-Import Rules

• Source: modules/modules.nix uses inputs.self.lib.autoImport for legacy flat .nix files and inputs.self.lib.autoImportLeaf for nested nixos.nix files.
• Home Manager source: config/base.nix registers modules/home-manager.nix in home-manager.sharedModules, and that module uses inputs.self.lib.autoImportLeaf to discover nested home.nix files anywhere under modules/.
• Filter: Legacy flat auto-import excludes librewolf.nix; nested split modules are discovered by exact leaf name (nixos.nix or home.nix).
• Preferred layout: modules/<category>/<name>/nixos.nix and modules/<category>/<name>/home.nix.
• Migration rule: Legacy flat modules/<category>/<name>.nix modules remain supported while features are moved into split directories.
• Implication: Place new dual-surface modules in a feature directory so NixOS and Home Manager stay adjacent; no manual import wiring is required unless adding a new factory.

Hosts and Roles

• Configs: hosts/<name>/configuration.nix with toggles in hosts/<name>/toggles.nix.
• Active hosts: workstation, server, miniserver, galaxy, emacs, vps.
• Roles:
  • workstation: developer desktop; provides build power for distributed builds.
  • server: primary services host; runs most services and WireGuard targets.
  • miniserver: small-footprint server.
  • galaxy: small server variant using nixpkgs-small.
  • emacs: VM profile, my.secureHost = false for secret-free usage.
  • vps: Linode VPS image target, secure host with enrollment-based secrets.
• Network maps: my.ips and my.interfaces declared in modules/modules.nix; host toggles may override.

Proxy, Firewall, and Networking

• Proxy enablement: my.enableProxy toggles Nginx reverse proxy; assertions require at least one my.servers.*.enableProxy when enabled.
• Proxy helpers: use parts/core.nix helpers (proxy, proxyReverse, proxyReverseFix for header preservation, proxyReversePrivate for mutual TLS). mkserver supplies host, ip, url, enableProxy, and useDefaultProxy.
• Default proxying: any server with enableProxy = true gets a proxyReverse vhost unless useDefaultProxy = false or it is listed in proxyReverseFix / proxyReversePrivate.
• Main server selection: my.mainServer chooses where services live by default (default vps); mkserver sets isLocal based on this and picks IPs from my.ips.
• Firewall generation: inputs.self.lib.generateFirewallPorts combines static ports, additional ports, and service ports from my.servers (excluding native firewall services). Use my.network.firewall settings and getServicesWithNativeFirewall to derive open ports.

Secrets Map

• Files and purposes:
  • secrets/certs.yaml → certificates and TLS material.
  • secrets/env.yaml → environment variables for services (e.g., lidarr-mb-gap).
  • secrets/gallery.yaml → media/gallery credentials.
  • secrets/homepage.yaml → homepage widget secrets.
  • secrets/keys.yaml → SSH/private keys and key ownership.
  • secrets/wireguard.yaml → WireGuard peers and private keys.
  • secrets/secrets.yaml → default SOPS file (general secrets, fallback when unspecified).
  • secrets/ssh/ → host SSH keys and related artifacts.
• secureHost: Only hosts with my.secureHost = true consume SOPS entries and WireGuard interfaces. Keep secret references behind lib.mkIf config.my.secureHost; proxy-only services that use private certs must still declare their cert secrets when enableProxy = true.

Stylix and Theming

• Stylix module: config/stylix.nix and stylix inputs in flake.nix apply theming. Host toggle my.stylix.enable controls activation (see host toggles).
• Schemes and assets: Imported via Stylix inputs; wallpapers/fonts sourced from external flakes (wallpapers, fonts).

Playbooks and Templates

• Playbook template: docs/playbooks/template.md
• Playbook: docs/playbooks/add-module.md — add a module in the right category and confirm auto-import.
• Playbook: docs/playbooks/split-home-manager.md — migrate a mixed module into paired nixos.nix and home.nix files.
• Playbook: docs/playbooks/add-server.md — add a reverse-proxied server via mkserver and proxy rules.
• Playbook: docs/playbooks/add-script.md — add a script unit via mkscript with install/service/timer options.
• Playbook: docs/playbooks/add-host-toggle.md — add or update host toggle maps under hosts/<name>/toggles.nix.
• Playbook: docs/playbooks/add-secret.md — add a SOPS secret in the correct file and wire it into modules.
• Playbook: docs/playbooks/add-wireguard-peer.md — add a WireGuard peer and update secrets/hosts.
• Playbook: docs/playbooks/enroll-vps.md — enroll a VPS key, re-encrypt secrets, redeploy.
• Playbook: docs/playbooks/vps-rebuild.md — rebuild the VPS with the expected deploy flow.
• Constitution link-back: docs/constitution.md sections on terminology, proxies, secrets, and maintenance.
• MCP server reference: docs/reference/mcp-server.md (tool catalog, nixos-mcp wrapper, invocation, sync-docs)

Quick Audit Checklist

• Module coverage: All categories (apps, dev, scripts, servers, services, shell, websites, network, users, nix) have corresponding entries and auto-import rules for both legacy flat modules and split nixos.nix/home.nix modules; patches/ is documented as a root directory.
• Host coverage: Active hosts listed with roles and secureHost status; mainServer noted.
• Proxy rules: enableProxy usage, proxy helper selection, and my.ips mappings documented.
• Secrets map: Every secrets file and secureHost gating captured; new secret types aligned to file purposes.
• Discoverability: Paths reachable within two clicks from docs/constitution.md.