87 lines
7.5 KiB
Markdown
87 lines
7.5 KiB
Markdown
# 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`.
|