Clustering

Clustering

Clustering lets multiple Portal instances share player presence over Redis, so a FindPlayerRequest sent to one proxy can resolve a player connected to a different proxy in the same network. See Network Architecture for why you'd run more than one instance.

Enabling it

In config.json (see Configuration for the full reference):

"cluster": {
  "enabled": true,
  "proxy_id": "",
  "ttl_seconds": 300,
  "redis": {
    "address": "localhost:6379",
    "password": "",
    "db": 0
  }
}

Key	Description	Default
cluster.enabled	Turn clustering on	false
cluster.proxy_id	ID this proxy reports itself as in the cluster. Empty = the machine's hostname	""
cluster.ttl_seconds	How long a player's presence record survives without a refresh before expiring — a crash safety net	300
cluster.redis.address	Redis server address (host:port)	localhost:6379
cluster.redis.password	Redis auth password, if required	""
cluster.redis.db	Redis logical database index	0

All Portal instances in the cluster should point at the same Redis instance/database.

What it does — and doesn't — do

When cluster.enabled is set, FindPlayerResponse (see Socket Protocol) gains a populated Proxy field when the player is found on a different proxy via the shared Redis backend, rather than this proxy's local session store.

That's the extent of it: clustering answers "is this player online, and which proxy are they on" across your fleet. It does not implement proxy-to-proxy transfer routing — a backend server that gets back a remote Proxy still needs its own way to act on that (e.g. relaying a message to that proxy/its backends), since Portal itself won't hop the player between proxies for you.