Install the relay
Last updated
Installing a Weald relay takes three commands, which fetch the bundle, set a hostname and start it. First boot migrates the database, issues a certificate and prints a bootstrap invite you have twenty-four hours to redeem. Read requirements first if you have not picked a host yet.
Run the install
curl -fsSL https://get.weald.team/relay | sh cd weald-relay && cp .env.example .env && $EDITOR .env docker compose up -d
The environment file that opens in the second command needs one value from you, the hostname. Every other value has a working default, and Configuration covers the ones you may want to change.
What starts
| Container | Job |
|---|---|
| relay | The Weald relay itself, serving the client WebSocket over TLS |
| postgres | Envelopes, access sets, invites and the transparency log |
| object storage | Encrypted media blobs, which the relay has no key for |
| redis | Live fanout between relay processes, holding no durable state |
| tls | Certificate issuance and renewal on port 80 and 443 |
Redis carries fanout only. A lost Redis message costs a subscriber one live push, and reconciliation repairs it on the next round trip. Envelope acceptance never depends on Redis.
First boot
First run migrates the schema, generates a single-use genesis key, and prints two values.
- A one-time enrollment URL carrying the relay hostname, the genesis-key fingerprint and the TLS-key fingerprint.
- The genesis fingerprint on its own, which is the value every later transparency-log entry chains back to.
Copy both before you close the terminal. The URL expires after twenty-four hours or on first use, whichever comes first. The first device to open it becomes the workspace trust root.
Point the app at it
Install the Mac app, then open the enrollment URL on the machine you want to be the first admin. The app asks for the relay hostname and the enrollment link and checks the genesis fingerprint against the one the relay printed. It then takes you through the recovery phrase before it contacts the relay.
First workspace covers that sequence and the invites that follow it.
Check it is healthy
The public listener serves liveness only. Readiness and metrics bind to a private listener on loopback by default, so a self-hosted relay keeps its storage totals and security state off the internet.
GET /healthzon the public listener answers whether the process is alive.GET /readyzon the private listener answers whether Postgres and object storage are reachable, and reports whether the access set is being enforced.
If setup fails, the health check names the failed dependency in words instead of printing a certificate stack trace. Troubleshooting lists what each one means.