Jitsi multi-region deployment with region-based bridge selection

Jicofo chooses a bridge by comparing two regions: the region it has learned for a participant and the region it is configured to treat as its own. With region-based bridge selection enabled, Jicofo prefers a videobridge in the participant's region, so the media for a meeting starts close to the people in it. The decision depends on four steps working in order. A fault in any one of them may not produce an error message. It is more likely to show up as a meeting placed on a bridge far from its participants, so the sequence is worth understanding before anything goes live.

The first two steps happen at the edge and in the signaling layer. The ingress in front of Jitsi adds an X-Proxy-Region HTTP header to requests, and Prosody copies that region into each participant's presence so that Jicofo can read it. Your ingress is usually a cloud load balancer or reverse proxy that you configure yourself, and the handbook assumes DNS routes users to a regional entry point. Confirm that the header reaches Prosody on the signaling path you actually use, and that the jiconop, muc_meeting_id and jitsi_session modules carry region_name in your Prosody configuration. A test client joining from each region, with a look at the presence it receives, is the simplest check.

The third step is the comparison. Jicofo uses jicofo.local-region to identify the region it serves, and each bridge sets videobridge.relay.region to its own region. When a participant's region matches a bridge's region, Jicofo places the conference on that bridge. The fourth step covers the case where the nearest region has no suitable bridge available. Conference media can then be relayed between bridges in different regions. The exact relay and fallback behavior depends on the Jitsi release you run, so confirm it against the region-based setup section of the handbook and test that scenario in staging before you rely on it for users in a specific country or office.

Capacity follows the same logic. The scalable setup guide says videobridges scale horizontally by adding more of them, and the default install is already configured for that. Each region needs enough bridges for its expected load. Check the sizing guidance in that guide against your own meeting profile, and ask your team or partner to document the expected load per region before go-live. Region names, relay settings and Prosody modules must match across every bridge and central server, which is why the guide recommends configuration management tools such as Ansible or Puppet. Keep region settings in version-controlled templates so that a new bridge in one region cannot quietly start with the wrong label.

The handbook's region design assumes two things from your edge. The first is DNS routing from a cloud provider, so each user reaches an entry point in a sensible region. The second is an ingress that adds an X-Proxy-Region HTTP header to requests. Prosody adds that value to participant presence, and Jicofo reads it when it selects a bridge. If either piece is missing, bridge selection cannot be region-aware and users fall back to whatever default your Jicofo settings produce. Before you commit to the design, confirm that your DNS provider can answer with a different regional name or address for each region, and confirm which ingress products in your environment can set a custom header from a region value you derive.

If your platform differs from the handbook's assumption, you must build or confirm the equivalent. A cloud load balancer may insert headers from a per-region listener or a rule keyed on the region. A self-managed reverse proxy can set headers from configuration, but the region value must come from a source you control. A CDN in front of the platform may supply its own geographic header, and you must map that header to X-Proxy-Region exactly. On-premises DNS often lacks latency or geographic answers, so you may need a global load balancing appliance or a split by network segment. Confirm each option with the product vendor and test it with your own traffic.

A client can send an X-Proxy-Region header itself. Unless the edge removes any inbound copy of that header, a user could force a bridge in another region, which adds latency and may move media across a boundary your data residency policy forbids. Set the header only at the edge, strip inbound copies on every listener, including listeners you consider internal, and verify with a request carrying a forged value that the backend sees only the edge value. Also restrict direct access to Prosody's BOSH and WebSocket endpoints so that traffic cannot skip the proxy and its header handling.

Some users will arrive without a usable region. Causes include networks missing from the geographic data, VPN exit points, mobile carriers, and ingress failures. Decide in writing which bridge pool serves these users, whether they go to a home region, and whether an unrecognized value is treated the same as a missing one. Test each path: a request with no header, a request with an unrecognized value, and a request during a failover. Log the region value for each join so unknown rates are visible over time. Ask the handbook's maintainers or your own test results how Jicofo handles a participant with no region value in your version, because that behavior decides whether users are placed on a bridge or fail to join.

Test region routing before any user relies on it, because a multi-region Jitsi setup can look healthy while every conference quietly lands on one bridge. The first test is a join from a client in each region. Use one test account per region, join a fresh room from each location, and confirm in the Jicofo logs that the conference was placed on the bridge that matches that region. Repeat each join with a second participant from the same region, since the placement you want is for the room, and a second joiner shows whether the bridge choice held. Record the room name, the bridge identifier and the time for each run so a later failure can be compared with a known good result.

Next, check that presence carries the region. The Jitsi handbook describes an ingress that adds an X-Proxy-Region HTTP header and Prosody copying it into participant presence for Jicofo. Confirm that the header is set by your ingress for each test region, that Prosody includes it in presence, and that Jicofo reads it when it chooses a bridge. Confirm the exact element names and log wording against the release documentation for the build you run, because the handbook is the reference for how these pieces connect and the lines you see in your own logs are what you should match against.

Then test the fallback path. Send joins with the header missing, with an unknown region value and with a region that has no bridge assigned. Each case should still produce a working conference on a bridge that you have decided is acceptable, usually a default or the local region. Treat a rejected join or an unexpected cross-region placement as a finding. Decide in advance which behavior is acceptable for users in a region with no bridge, because the answer affects data residency and latency commitments more than it affects the code.

Finally, test failover by stopping one regional bridge during a controlled window and joining from that region again. Watch Jicofo and the remaining bridges for how the conference is placed, and confirm that users reach a working meeting without manual changes. Capture logs from Jicofo and from every bridge for each test, keep them with the test record, and compare them with the expected output in the release notes for your build before signing off.