# Playbook: Add a Server Module with mkserver

- Name: Add a reverse-proxied server module
- Purpose: Stand up a server using `modules/factories/mkserver.nix` with correct proxy and host routing.
- Prerequisites: Target host must have `my.enableProxy = true` and container support if needed; confirm `my.secureHost` for secrets.
- Inputs: Service name, desired subdomain, port, proxy type (standard/fix/private), cron needs, secrets/env vars.
- Steps:
  1. Create `modules/servers/<name>.nix` and import `mkserver` options to define `enable`, `enableProxy`, `port`, `host`, `hostName`, `url`, `ip`, `enableSocket`, and `certPath` as needed.
  2. Default host routing uses `my.mainServer` and `my.ips`; override `hostName`/`ip` only when the service must live elsewhere.
  3. For reverse proxy behavior, select helper from `parts/core.nix`: `proxyReverse` (standard), `proxyReverseFix` (preserve host headers/websockets), or `proxyReversePrivate` (mutual TLS).
  4. Place secrets/env references in the appropriate file from the secrets map and guard with `lib.mkIf config.my.secureHost`.
  5. Enable the service toggle in `hosts/<host>/toggles.nix` under `servers` (and `enableProxy` if not already set); add any firewall/static ports needed.
- Validation:
  - Service resolves to the expected URL and IP per `my.ips` and `my.mainServer`.
  - Proxy helper matches the protocol needs; SSL settings align with cert sources.
  - Secrets load only on secure hosts; firewall assertions pass.
- Outputs: New server module with mkserver options and updated host toggles/firewall settings.
- References: `docs/constitution.md` (Main server and proxies, Secrets Map), `docs/reference/index.md` (Proxy rules, Module Directories, Secrets Map, Hosts and Roles)