Adds a how-to guide for self-hosting a STUN server with coturn and
pointing `CODER_DERP_SERVER_STUN_ADDRESSES` at it.
The guide is linked from the STUN and NAT page, the networking overview,
and the air-gapped comparison table.
Refs #16537, DOCS-310
**Verification**
- Both coturn install paths were run on an Ubuntu 24.04 VM and checked
with `coder netcheck` against a v2.39.0 deployment configured with only
self-hosted STUN servers: the coturn 4.6 package under systemd with the
documented config, and the `coturn/coturn:4.18.0` container with a
published UDP port. Hostname and IP entries in
`CODER_DERP_SERVER_STUN_ADDRESSES` both worked.
- A client on a separate home NAT network got `p2p` connections from
`coder ping`, and the STUN servers logged requests from both the client
and the agent. With the STUN servers stopped, connections fell back to
DERP and `coder ping` printed the "could not connect to STUN over UDP"
hints. Running workspaces picked up the new STUN list without a restart.
- Custom relay map path, checked in-process only (a throwaway
`derphealth` test, not committed): with a nil built-in region,
`tailnet.NewDERPMap` drops `CODER_DERP_SERVER_STUN_ADDRESSES`, and
hand-written STUN-only regions loaded from a relay map file report
`can_stun: true`. The documented `jq` filter lists them for both
built-in and custom maps.
- Source-verified only: each address becomes its own STUN-only region
(`tailnet.STUNRegions`), which backs the "two or more servers" advice.
With the built-in relay off, a relay map that has only STUN-only nodes
fails startup (`tailnet.NewDERPMap`, pinned by
`TestNewDERPMap/RequireDERPNodes`), which backs the "keep at least one
relay node" note.
- Not tested: Kubernetes or ingress setups. The VM-only guidance follows
Spike's comment on #16537.
markdownlint, Vale, `lint/emdash`, `lint/docs-manifest`, and
`lint/docs-html` pass on the changed files, and a doc-check self-check
left no blocking findings.
<details>
<summary>Decision log</summary>
- **Dropped `stund`.** It has no releases, packages, or container
images, so the guide had readers build an unpinned binary from
Tailscale's `main` branch with no distribution security updates. It also
answers only binding requests that carry a `FINGERPRINT` attribute, so
generic STUN test tools can't check it. Its only advantage over coturn
is a smaller, memory-safe, STUN-only codebase, and coturn's `stun-only`
mode covers the practical need.
- **The built-in relay is optional unless you use
`CODER_DERP_SERVER_STUN_ADDRESSES`.** `cli/server.go` sets the built-in
region to `nil` when `CODER_DERP_SERVER_ENABLE=false`, and
`tailnet.NewDERPMap` adds STUN regions only when that region exists,
numbering them from its region ID. Deployments with a custom relay map
add STUN-only regions to that map instead, so the prerequisite became a
"Use a custom relay map" section under Configure Coder. The page doesn't
drop the relay entirely, because the built-in relay is still required
for `CODER_DERP_SERVER_STUN_ADDRESSES`, and a custom relay map still
needs at least one relay node.
- **Changed the `jq` filter.** The old filter matched generated
`coder_stun_*` region codes, so it returned an empty list for STUN
regions written into a custom relay map. The filter now selects nodes
with `STUNOnly` set.
</details>
Supersedes #31802, reopened under a human author for attribution.
---
_Generated with Coder Agents on behalf of @nickvigilante._
---------
Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>