NixOS/docs/playbooks/add-server.md

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)