Live map relays (optional computers)

Opening the Live Map in a browser or on a phone does not require you to know any relay address. SwapSanity picks machines that have volunteered.

This page is only if you want to run a computer as a relay (clubhouse laptop, timing tent, or a public always-on box).

Do I need ports 80 and 443 and a certificate?

No, not for every relay.

The live map uses several paths. Relays are only required for some of them.

You want to…	Open port 80?	Open 443 + TLS certificate (e.g. Let’s Encrypt)?
Help phones in the field (Iroh / Wi‑Fi UDP / Bluetooth)	No	No
Show the map on screens on the same venue Wi‑Fi	No	No — a normal port such as 8080 and `ws://` on the LAN is enough
Let people on the public website (home browsers, Tesla, etc.) use this computer	No*	Yes — browsers on an `https://` site will only talk to `wss://your-hostname/…` (TLS, usually port 443)

* Port 80 is not required by SwapSanity. It is only useful if you use Let’s Encrypt HTTP-01 to create or renew the certificate. If you already have a cert (or use DNS-01), you can leave 80 closed.

Why 443 for internet browsers?

The SwapSanity web app is served over HTTPS. Browsers block insecure ws:// from that page. A public relay (including a “backup for everyone”) must therefore present a real hostname and certificate on 443. The app does not connect to a raw bind port such as ws://host:55820. Iroh hole-punch does not open a campus firewall; use wss://hostname/mesh-stream on 443.

A group-only laptop at the event does not.

Phones and tablets share live positions over Iroh gossip (internet / cellular) and, on the same Wi‑Fi name, over local UDP (IPv4 and IPv6). Those paths do not need you to type a relay address. UDP does not need internet, a relay, or port 443. If two devices on the same network still do not see a UDP link, the router may be blocking device-to-device traffic (client isolation).

The map can still show dots from the slower cloud path if gossip has no neighbors. Sub-second motion is gossip (and same-LAN UDP). A helper computer joins the same gossip topics as its logged-in groups so browsers on wss:// can watch.

Who never thinks about this

Map users, spectators, and racers. Discovery and load-balancing are automatic. Volunteers are not given all of a group’s traffic when a public relay is up.

Running a relay (operators)

Typical clubhouse (LAN only). If you are logged in, all of your groups are relayed and logged by default (separate files per group). Pass --group-id to limit that list; pass --event-id for a separate event log:

swapsanity_cli --env sandbox edge-relay --opt-in --port 8080
swapsanity_cli --env sandbox edge-relay --opt-in \
  --group-id YOUR_GROUP --event-id YOUR_EVENT --port 8080

Logs land under ~/.swapsanity/mesh_blackbox/{sandbox|production}/groups/{id}/ as encrypted SSMH (mesh_hearsay.dat) — 68-byte GPS envelopes, no plaintext coordinates on a public helper. After the session is reconstructed and uploaded you can mark them deletable:

swapsanity_cli mesh-log-mark --group-id YOUR_GROUP --status reconstructed
swapsanity_cli mesh-log-mark --group-id YOUR_GROUP --status uploaded

Always-on public box (this is what a server with Let’s Encrypt looks like). Public volunteer is off unless you pass --public-relay:

swapsanity_cli edge-relay --opt-in --group-id YOUR_GROUP \
  --port 443 --tls-cert /path/fullchain.pem --tls-key /path/privkey.pem \
  --announce-url wss://your.hostname/mesh-stream \
  --public-relay

--public-relay means “also help other groups if needed.” It is not the default. You still need 443 + a cert for internet browsers. --announce-url is the public wss:// name (not a bind IP, so it matches the certificate). Viewers still do not type it.

Live GPS is encrypted. A public helper forwards ciphertext and can save SSMH for coaches to rebuild later; it cannot plot the map. Details: Live map privacy.

One machine can relay several groups and events at the same time; their reconstruction logs stay separate.

You can run many relays. The app prefers a public backup plus optional extra capacity from a group volunteer so volunteering does not overload a home connection. Merging logs from several relays after an event is a later step.

Sandbox and production on the same computer

The always-on host can run two relay processes (systemd instances). They do not share a Firebase project, port, or log directory. Each process announces wss:// plus this machine’s DNS name (hostname -f), not localhost.

	Sandbox	Production
Command env	`--env sandbox`	`--env production`
Browser URL	`wss://<this-host>:80/mesh-stream`	`wss://<this-host>/mesh-stream` (port 443)
Operators	`systemctl start swapsanity-mesh-relay@sandbox`	`systemctl start swapsanity-mesh-relay@production`

Clubhouse laptops still use a single edge-relay --opt-in for the env they are logged into.