Names and certificates
Last updated
A Weald relay needs one hostname and one DNS record pointing at the host. Port 80 has to be reachable long enough for a certificate to be issued. The bundled TLS terminator handles issuance and renewal, so on the default path you configure the name and nothing else.
Behind a proxy you already run, turn the relay's own TLS off and terminate in front of it.
The DNS record
Point an A record, or an AAAA record, at the host and set the same name as WEALD_RELAY_HOSTNAME. Clients connect by that name, and it is part of the enrollment link the relay prints on first boot. Changing it later means re-enrolling devices.
| 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 |
A certificate authority completing an HTTP challenge reaches the host on port 80. If you close it, renewal fails silently sixty days later.
The three TLS modes
WEALD_RELAY_TLS takes one of three values, chosen by who terminates TLS.
acme, the default. The bundle obtains and renews a certificate for the hostname automatically. Use it 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 proxy 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. The proxy has to get two things right.
- WebSocket upgrade has to pass through. It carries the whole client transport. A proxy that buffers or strips the upgrade leaves 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. Large media uploads would fail in a way that looks like a client bug.
No public ingress at all
The private network path is supported. Bind the relay to a Tailscale or WireGuard interface and have clients reach it over the same network. There is no ACME, no public DNS record and nothing exposed to the internet.
On this deployment you can reasonably turn access set enforcement off, 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, so a device notices a later certificate substitution.
Rotating a certificate normally is fine. Members' devices report a replaced key underneath it, so plan that change in advance.