livqenoDocs

ResourcesRegions

Regions

Placing rooms and TURN relays near your users when Livqeno runs in more than one region.

A self-hosted Livqeno deployment can run media servers (SFUs) and TURN relays in several regions. The API then puts each new room, and each user's relay list, as close to the user as it can. A single-region deployment needs none of this and behaves exactly as before.

Configure the regions

Set REGIONS on the API to a JSON list of regions, with each region's centre and the countries it serves:

REGIONS='[{"id":"ap-south","name":"Mumbai","lat":19.08,"lon":72.88,"countries":["IN","LK","NP","BD","PK"]},
          {"id":"eu-central","name":"Frankfurt","lat":50.11,"lon":8.68,"countries":["DE","FR","NL","GB"]},
          {"id":"us-east","name":"Virginia","lat":38.9,"lon":-77.0,"countries":["US","CA","BR","MX"]}]'
API_REGION=eu-central        # where this API instance runs

Each SFU names its region with SFU_REGION, which must match a region id. TURN relays are tagged in TURN_HOSTS as host[:port][@region]:

TURN_HOSTS=turn-in.example.com@ap-south,turn-us.example.com:3478@us-east

How a user's region is found

The API works out a client region each time a token is made and each time someone joins. It uses the first of these that gives an answer:

  1. A region you pass: in the token request (POST /v1/rooms/{roomId}/rtc-tokens with { "region": "ap-south" }) or in the client's room.join. It must be one of your regions; a token request with an unknown one gets a 400.
  2. Cloudflare's CF-IPCountry header, but only with TRUST_CF_HEADERS=true. Leave this off unless Cloudflare really is in front of the API, because anyone can send the header otherwise.
  3. A MaxMind GeoLite2 database at GEOIP_DB_PATH, if you provide one.
  4. API_REGION.

Tokens are usually made by your backend, so rules 2 and 3 locate your backend, not your user. If your backend knows where the user is, pass region in the token request.

room.joined reports region (where the media server is) and clientRegion (where the user was placed).

What the region changes

  • New rooms go to a media server in the user's region. If that region is full or has none, the nearest region with room is used.
  • Existing rooms never move. Everyone in a call shares one media server, so later joiners use the room's server wherever they are.
  • Live streams can reach far-away viewers through an edge in their own region, once they are more than CASCADE_MIN_DISTANCE_KM (2,500 km by default) from the stream's server.
  • TURN relays are listed with the user's region first, then the nearest other region (at most two regions), then any untagged relays.

Next steps

Edit this page on GitHub