Relay - alternative installations

[Frankynov]

Hello,
I'm thinking about using the relay feature for one of my future devices that I will probably lay at my parents home.
There is of course the official relay, and I saw there is an option to selfhost it using cloudflare : https://docs.tesserae.ink/relay/self-host/
Thing is, I don't really use cloudflare - or don't want to use it just for this case.
What do you think about being able to use a docker image for it, or even "bare metal" in a LXC container for example ?
I guess the features on this remain quite static so maintenance and updates should be quite bearable.
Thank you !

[dmellok]

Built it, and there is an image to pull rather than a repo to clone.

docker run -d --name tesserae-relay \
  -p 8787:8787 \
  -v relay-data:/data \
  ghcr.io/dmellok/tesserae-relay:edge

Multi-arch (amd64 and arm64). :edge tracks main and every build also publishes an immutable sha-<commit> tag if you would rather pin; :latest appears with the first tagged relay release. Without Docker it runs on anything with Node 18 or newer: RELAY_DATA_DIR=/var/lib/tesserae-relay npm start from packages/relay.

Knobs are RELAY_DATA_DIR, PORT, HOST and RELAY_MAX_BODY. GET /healthz answers 200 ok for container health checks.

The important part: it is the same src/index.js the Cloudflare deployment runs, with the filesystem standing in for R2. The Worker was never really Cloudflare-specific; the coupling was one bucket binding used as a blob store. So the wire contract is untouched and a panel paired against the hosted relay reaches yours by changing its base URL. No firmware change, and no second implementation to drift out of sync.

It speaks plain HTTP, so terminate TLS in front of it. With Caddy that is:

relay.example.com {
    reverse_proxy 127.0.0.1:8787
}

That is the piece Cloudflare was giving away. A relay has to be publicly reachable by both your install and the panel, so a small VPS rather than something behind your home router. What you expose is a zero-knowledge mailbox holding opaque sealed blobs that never sees a frame key, which is a much smaller surface than exposing the install itself.

One correction to what I said earlier about storage. Frame blobs do not accumulate: each upload deletes the frame it supersedes, so a mailbox holds one sealed frame per device. What does grow is abandoned pairing records, which the Cloudflare deployment expires with an R2 lifecycle rule. A container has no lifecycle rules, so it sweeps code/ and pair/ hourly against the expires_at those records already carry. Nothing for you to configure or cron.

Run a single instance. Storage is a plain directory, and several replicas over a shared volume would race on the read-modify-write paths, token rotation in particular.

Docs: https://docs.tesserae.ink/relay/self-host/

Worth saying that CI built this image before I could: Docker was not running on my machine, so the container has been exercised through its test suite and its entrypoint but nobody has yet run the published image end to end. If you do try it, I would like to hear whether the first pairing goes cleanly.

[dmellok]

Tagged now, so there is a stable tag rather than a moving one:

docker run -d --name tesserae-relay \
  -p 8787:8787 \
  -v relay-data:/data \
  ghcr.io/dmellok/tesserae-relay:latest

:latest is relay v0.1.0; :0.1 and :0.1.0 pin harder if you would rather not follow releases automatically. :edge still tracks main for unreleased changes. Worth preferring a release tag for something a panel depends on, since :edge moves under you.

The docs now lead with :latest too.

[Frankynov]

This is perfect, and I confirm it's now working !
Thank you very much !