Scaling out: origin + edge clusters

When one node is not enough

A single StreamHub server handles a lot — many concurrent rooms on a mid-size VM. But at some point you want to spread load geographically or absorb more concurrent publishers than one box can. That is where clustering comes in.

Origin and edge

The model is origin + edge:

• The origin is the first node you install. It self-registers in the global nodes table and owns the authoritative registry.
• Edge nodes are installed with a join flag. They register against the origin and then heartbeat every 60 seconds so the origin knows they are alive.

The installer supports both shapes directly — an origin install and a --join install — and ships a heartbeat timer so liveness is automatic.

Installing an edge node

curl -fsSL https://www.streamhub.studio/install.sh | sudo bash -s -- \
  --join --origin https://media.example.com --token <join-token>

The edge pulls the same pinned stack, registers itself, and starts heartbeating. From the origin you can see every node and its last-seen time via /api/v1/nodes.

What the cluster gives you

• A shared view of nodes and their health from the origin.
• The ability to place media services closer to publishers or viewers.
• A single control plane — you manage the fleet from the origin's registry.

Know the boundaries

Clustering is real but scoped, and it is honest about its limits. Before you design around it, read the two operations docs that spell out exactly what is covered versus what is a known limitation: the node install guide and the two-node test writeup. Treat cross-node behavior as documented-and-tested rather than assume full active-active parity — the docs are explicit about which flows are proven end-to-end.

The pragmatic path

For most workloads a single well-provisioned origin is the right answer, and vertical scale plus HLS (which is CDN-friendly and cheap to fan out) carries you a long way. Reach for edges when you genuinely need geographic distribution or publisher capacity beyond one node — and lean on the node docs to stay inside the tested envelope.