boma/roles/netbird_coordinator/README.md

# netbird_coordinator

Self-hosted **NetBird coordinator** — the mesh-VPN control plane (ADR-016). Runs on
`askari` (the off-site Hetzner host) and is the rendezvous point every NetBird peer
talks to. Deployed via Docker Compose (ADR-004), behind the Caddy reverse proxy.

## Architecture — combined server

NetBird's self-hosted stack is now a **single combined server image** plus a separate
dashboard UI — there is no longer a separate signal / relay / coturn / dex container,
and no `turnserver.conf` / `management.json` / `openid-configuration.json`.

| Container | Image | Role |
|---|---|---|
| `netbird-server` | `netbirdio/netbird-server` | Management API + Signal + Relay + STUN + embedded Dex IdP (`/oauth2`), all on one process. Config at `/etc/netbird/config.yaml`. State in the `netbird_data` volume (SQLite). |
| `netbird-dashboard` | `netbirdio/dashboard` | Web UI. Configured purely by environment (`dashboard.env`); a public PKCE OIDC client, so its client secret is intentionally empty. |

Both containers join the **existing external `boma` Docker network** (created by the
`reverse_proxy` role's compose) so Caddy reaches them by container name. The only
host-exposed port is **`3478/udp` (STUN)**; HTTP/gRPC/WS traffic enters via Caddy over
the boma network, not via host ports.

### Reverse-proxy routing (added separately — M4a Caddy)

This role does **not** add the Caddy route. The route is a separate task and must
front several upstreams on `netbird-server` over the boma network, all to the same
backend:

- Native gRPC (signal + management) — matched by **`Content-Type: application/grpc*`**
  (not by path) → `h2c://netbird-server:80`
- HTTP + WebSocket — paths `/relay*`, `/ws-proxy/*`, `/api/*`, `/oauth2/*` → `netbird-server:80`
- Dashboard catch-all — `/*` → `netbird-dashboard:80`

This matches NetBird's own external-proxy Caddy example: gRPC (the
`/management.ManagementService/*` + `/signalexchange.SignalExchange/*` services) is
selected by content-type rather than enumerated by path. gRPC needs HTTP/2 (h2c)
upstream support; WS/gRPC need long timeouts (Caddy sets none by default).

## Variables — `netbird_coordinator__*`

| Variable | Default | Description |
|---|---|---|
| `netbird_coordinator__server_image` | `netbirdio/netbird-server:0.72.4` | Combined server image (pinned; never `latest`) |
| `netbird_coordinator__dashboard_image` | `netbirdio/dashboard:v2.39.0` | Dashboard image (versioned independently of the server) |
| `netbird_coordinator__base_dir` | `/opt/services/netbird` | Working directory for the Compose project |
| `netbird_coordinator__domain` | `netbird.askari.wingu.me` | Public hostname; feeds `exposedAddress`, the OIDC issuer, redirect URIs, and the dashboard endpoints |
| `netbird_coordinator__trusted_proxies` | `["172.16.0.0/12"]` | Source ranges NetBird trusts `X-Forwarded-*` from (`server.reverseProxy.trustedHTTPProxies`). Must cover Caddy's source IP on the boma network — verify the actual bridge subnet at deploy |
| `netbird_coordinator__manage` | `true` | Set `false` in Molecule to render templates without a Docker daemon |
| `netbird_coordinator__disable_geolocation` | `true` | sets `NB_DISABLE_GEOLOCATION` so a no-egress startup can't FATAL the server on the GeoLite2 download (FRICTION 2026-06-17 #4) |

Production overrides live in `inventories/production/group_vars/`.

## Secrets

Two secrets come from the vault and are rendered into the host-side `config.yaml`
(mode 0640, `no_log`); they never touch the work tree or the dashboard:

- `vault.netbird.auth_secret` — `server.authSecret`
- `vault.netbird.datastore_key` — `server.store.encryptionKey` (base64; keep the padding)

The dashboard's OIDC client is a public PKCE client, so `AUTH_CLIENT_SECRET` is
intentionally empty — `dashboard.env` carries no secrets.

## `netbird_coordinator__manage` toggle

Docker operations (`docker compose up`, the restart handler) are gated on
`netbird_coordinator__manage | bool`. Molecule sets it `false` so the role can be tested
(template rendering, directory creation) without a Docker daemon.