67 lines
4.7 KiB
Markdown
67 lines
4.7 KiB
Markdown
# 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)
|
|
- 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 (overrides `my.mainServer = "server"` and enables proxies/containers).
|
|
- miniserver: small-footprint server; default `mainServer` in shared options.
|
|
- 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`, and `enableProxy` defaults per service.
|
|
- Main server selection: `my.mainServer` chooses where services live by default; `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`.
|
|
|
|
## 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, 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`.
|