The environment file
Last updated
A Weald relay reads three required environment variables and about ten optional ones. The required three are a hostname, a database URL and a storage URL, and every other value has a working default. The set is kept small because a key that quietly widens a security boundary does more harm than a missing feature.
Required
WEALD_RELAY_HOSTNAME relay.example.com WEALD_RELAY_DATABASE_URL postgres://... WEALD_RELAY_STORAGE_URL s3://bucket | file:///var/lib/wealdrelay/blobs
The compose bundle fills in the second and third from the containers it starts. On the default path you edit the hostname line and nothing else.
Optional
| Variable | Default | What it decides |
|---|---|---|
WEALD_RELAY_REDIS_URL | unset | Live fanout between processes. Unset means single-process mode |
WEALD_RELAY_LISTEN | 0.0.0.0:8443 | The address the client WebSocket binds to |
WEALD_RELAY_TLS | acme | acme, file or off, the last for a proxy that terminates TLS |
WEALD_RELAY_MAX_STORAGE_GB | unlimited | A ceiling, after which writes are refused with a quota error |
WEALD_RELAY_RETENTION_DAYS | unlimited | How long history is kept below a checkpoint |
WEALD_RELAY_ACCESS_SET | enforce | Whether a revoked device can still open a socket |
WEALD_RELAY_SMTP_URL | unset | Lets the relay send invite mail. Self-host only |
WEALD_RELAY_WRITE_MODE | full | read_only refuses new durable writes and keeps reads working |
WEALD_RELAY_OBSERVABILITY_LISTEN | 127.0.0.1:9090 | The private health and metrics listener |
WEALD_RELAY_METRICS_GROUP_LABELS | off | Per-group envelope and byte counts in metrics |
WEALD_RELAY_RELEASE_CHECK | on | A daily unauthenticated GET of the public release feed |
The four that decide posture
WEALD_RELAY_ACCESS_SET. Leave it at enforce, which checks each connection against the group's access set, so revoking a device disconnects it. With off, any well-formed key may open a socket, which is reasonable only with no public ingress, and readiness output and every client's encryption panel say so.
WEALD_RELAY_SMTP_URL. Setting it lets your relay send invite mail, and your relay then holds invitee email addresses. That list of humans sits inside the otherwise blind half of the system, so it is unset by default and refused on the hosted tier.
WEALD_RELAY_METRICS_GROUP_LABELS. Off by default. Turning it on breaks envelope counts and byte totals out per group, which helps a self-hoster debug their own instance, and the hosted tier never enables it.
WEALD_RELAY_RELEASE_CHECK. The relay checks the public release feed once a day and reports the result on its readiness endpoint, so a client can tell an admin that a security release exists. The check is an unauthenticated GET of a public file, and an air-gapped install turns it off.
What is deliberately absent
There is no admin password, no operator account and no web admin panel. No configuration key names a billing system, a license server or a control plane. The three variables above are the complete required set.
A fourth required variable pointing at a hosted service would change the trust boundary. The hosted binary would then differ from the audited one, and a self-hoster would run something else. A flag that silently widened enrollment was removed for the same reason.