19 lines
1.8 KiB
Markdown
19 lines
1.8 KiB
Markdown
# Playbook: Add a NixOS Module
|
|
|
|
- Name: Add a module under `modules/<category>/`
|
|
- Purpose: Introduce a new module following auto-import and toggle conventions.
|
|
- Prerequisites: Identify target host(s) and toggle category; confirm `my.secureHost` if secrets are involved.
|
|
- Inputs: Module name, category (apps/dev/scripts/servers/services/shell/network), required options, secret needs, proxy requirements if server-facing.
|
|
- Steps:
|
|
1. Choose the category path from `docs/reference/index.md`. Prefer `modules/<category>/<name>/nixos.nix` plus `modules/<category>/<name>/home.nix` when the feature spans both system and Home Manager; use a legacy flat `modules/<category>/<name>.nix` only for NixOS-only modules or temporary migration work.
|
|
2. Define options under `my.<category>` or reuse factories (`mkserver` for servers, `mkscript` for scripts) instead of hand-rolled patterns.
|
|
3. If the module needs secrets, guard references with `lib.mkIf config.my.secureHost` and map them to the correct secrets file (see secrets map).
|
|
4. For networked services, align host selection with `my.mainServer` and `my.ips`; enable reverse proxy via `enableProxy` when applicable.
|
|
5. Wire toggles for target hosts in `hosts/<host>/toggles.nix`, ensuring users/groups and containers/proxy flags are set.
|
|
- Validation:
|
|
- Module loads without extra imports (`nixos.nix` and `home.nix` are auto-discovered; legacy flat modules remain supported).
|
|
- Toggle wiring matches intended hosts; secureHost gating present for secrets.
|
|
- Proxy and port choices align with `my.mainServer`, `my.ips`, and firewall rules.
|
|
- Outputs: New module file and updated host toggles if required.
|
|
- References: `docs/constitution.md` (Module Categories, Secrets Map, Main server and proxies), `docs/reference/index.md` (Module Directories, Auto-Import Rules, Proxy rules, Secrets Map)
|