19 lines
1.7 KiB
Markdown
19 lines
1.7 KiB
Markdown
# 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)
|