NixOS/docs/reference/index.md

Reference Map

Module Directories

• apps → modules/apps/ (desktop/workstation apps, auto-imported)
• dev → modules/dev/ (language toolchains and dev shells, auto-imported)
• scripts → modules/scripts/ (script units built via mkscript, auto-imported)
• servers → modules/servers/ (reverse-proxied services built via mkserver)
• services → modules/services/ (supporting services like syncthing, wireguard)
• shell → modules/shell/ (shell customizations and CLI tooling)
• websites → modules/websites/ (static nginx vhosts for portfolio/blog and reports)
• network → modules/network/ (networking rules, firewall helpers)
• users → modules/users/ (user-related options)
• nix → modules/nix/ (Nix configuration and helpers)
• patches → patches/ (patch artifacts referenced by modules)
• factories → modules/factories/ (mkserver.nix, mkscript.nix shared helpers)

Auto-Import Rules

• Source: modules/modules.nix uses inputs.self.lib.autoImport to load .nix files from module directories.
• Filter: Excludes librewolf.nix; all other .nix files in target dirs are loaded automatically.
• Implication: Place new modules in the correct category directory with a .nix filename; no manual import wiring 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
• Workflows: docs/playbooks/add-module.md, add-server.md, add-script.md, add-host-toggle.md, add-secret.md
• 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, patches) have corresponding entries and auto-import rules.
• 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.