Names and certificates
Last updated
A Weald relay needs one hostname, one DNS record pointing at the host, and port 80 reachable long enough for a certificate to be issued. The bundled TLS terminator handles issuance and renewal, so on the default path there is nothing to configure beyond the name. Behind a proxy you already run, turn the relay's own TLS off and terminate in front of it.
The one record
Point an A record, or an AAAA record, at the host and set the same name as WEALD_RELAY_HOSTNAME. Clients use that name to connect, and the name is part of the enrollment link the relay prints on first boot, so changing it later means re-enrolling devices rather than editing a setting.
| Port | Direction | Used for |
|---|---|---|
| 443 | inbound | The client WebSocket, over TLS |
| 80 | inbound | The certificate challenge, at issuance and at each renewal |
| 443 | outbound | The daily release check, unless it is turned off |
Port 80 is not a convenience. A certificate authority completing an HTTP challenge reaches the host on it, and closing it means renewal fails silently sixty days later rather than loudly today.
The three TLS modes
WEALD_RELAY_TLS takes one of three values, and which is right depends on who terminates.
acme, the default. The bundle obtains and renews a certificate for the hostname automatically. This is the right answer for a relay with public ingress.file. You supply a certificate and key, which suits an internal certificate authority or a wildcard your organisation already issues.off. The relay serves plaintext HTTP on its listener and something in front of it terminates TLS. Use this only when that something is on the same host or the same private network.
Behind a proxy
If you already run Caddy, nginx or a cloud load balancer, set WEALD_RELAY_TLS=off, set WEALD_RELAY_LISTEN to an address the proxy can reach, and forward to it. Two things the proxy has to get right:
- WebSocket upgrade has to pass through. This is the whole client transport, and a proxy that buffers or strips the upgrade produces a relay that answers a health check and serves nobody.
- Do not set a response body size limit below the relay's own envelope ceiling, or large media uploads fail in a way that looks like a client bug.
No public ingress at all
The private network path is supported, not merely tolerated. Bind the relay to a Tailscale or WireGuard interface, have clients reach it over the same network, and there is no ACME, no public DNS record and nothing exposed to the internet.
This is also the one deployment where turning access set enforcement off is a reasonable choice, because the network is already the boundary. Everywhere else, leave it enforcing.
Certificate fingerprints
The enrollment link the relay prints carries the TLS-key fingerprint alongside the genesis fingerprint. The client records it, which is what turns a later certificate substitution into something a device notices.
Rotating a certificate normally is fine. Replacing the key underneath it is a change members' devices will report, so plan it rather than discovering it.