Several tenants

Français · Type: how-to · Audience: admin · Context: Reality Bridge · Status: ready · Applies from: 4.2.5

The Reality Bridge, distributed profile (Postgres) · contract: experimental · verified by CI (support matrix of 4.4.0, 2026-10-23): Postgres 16 in CI; The qualification profile: HTTPS, three instances (ops/qualify/) · automated checks: jobs bridge-postgres, deployment-smoke; CI plan reality; 1 test file · people's passes: bridge-postgres-https not run (#77) · known limits: bridge-tenants-demo-webhooks, bridge-tenants-shared-process

How to serve several games, or one game in several environments, from one Bridge deployment, and how to run several instances of it on one store. A tenant is one operator's game in one environment: its own folder, its own Biscuit root, event key, operator token, quotas, rotation and revocations. What isolates them, and where that stops: Guarantees.

What you get

One serve (or several identical ones) holding several tenants on one SQL store, each reached by its own host name, each signing WorldSignalV2 signals that name their tenant, with connector tokens bound to their tenant.

Context and versions

• A Bridge, from 4.1.10 ("Constellation", ADR 0009, ADR 0010); this page applies from 4.2.5 (the quest-n-click-bridge names).
• Several tenants need a SQL store: SQLite for one machine, Postgres for several instances (the distributed profile, experimental).
• Verified on: not replayed for this page. The same layout (two tenants, three instances, one Postgres) is what npm run ops:qualify brings up and checks (The reference deployment).

Prerequisites

• A running single Bridge is understood first: Install and run the Bridge.
• One host name per tenant (bridge.a.example, bridge.b.example) pointing at the deployment, or a proxy that sets X-Web-Scumm-Tenant.
• For several instances: Postgres, and pg installed beside the Bridge.

Where to run the commands

On the deployment's machine (or each instance's), with one folder per tenant, for example /srv/bridge/a and /srv/bridge/b. npm run bridge -- … in the engine repository, npx quest-n-click-bridge … with the package (then pass --manifest= to init).

Steps

1. Make each tenant's folder, with its id, its environment and its host names:

   # on the deployment's machine, in the engine repository
   npm run bridge -- init --dir=/srv/bridge/a --tenant=a --environment=prod --hosts=bridge.a.example --no-demo-webhooks --origin=https://game-a.example
   npm run bridge -- init --dir=/srv/bridge/b --tenant=b --environment=staging --hosts=bridge.b.example --no-demo-webhooks --origin=https://game-b.example
   

   --environment is prod, staging or dev (prod by default); it is named in every signal and in the keys the tenant lists.

2. Serve them together on one SQL store:

   # on the deployment's machine, in the engine repository
   BRIDGE_STORE=postgres://… npm run bridge -- serve --tenants=/srv/bridge/a,/srv/bridge/b [--tenant-header]
   

   A request is routed by its Host (each tenant's hosts), or by X-Web-Scumm-Tenant with --tenant-header, before anything is read; no tenant, a 404. Two folders that configure the same tenant are refused at start, and so is a journal (several tenants share a SQL store: --store=sqlite:<file>, BRIDGE_STORE=postgres://… or BRIDGE_STORE_FILE).

3. Grant each tenant's connectors from that tenant's folder: grant adds the tenant to the token, so no other tenant accepts it.

   # on the deployment's machine, in the engine repository
   npm run bridge -- grant --dir=/srv/bridge/a --connector=mail-a --source=mail --signals=mail.answer.correct --pair > mail-a.token
   

4. For more capacity, start as many identical serve as needed on the same store, with no sticky sessions, behind a load balancer. Instances are stateless.

Expected result, and how to check it

• GET /healthz on any instance says "tenants": 2 and the store's kind.
• npm run bridge -- doctor --dir=/srv/bridge/a (with the same BRIDGE_STORE) lists every tenant of the store, with its players, signals, gaps and quarantined rows.
• A request with an unknown Host gets 404 {"error": "tenant"}.

How instances share one store

• Sequences, deduplication and acknowledgements are decided in one database transaction; delivery is at least once and applied once (D20).
• A signal accepted by one instance reaches a stream held by another, which reads the store when woken: Postgres NOTIFY, a 250 ms poll on SQLite, and a pass every 5 s should a wake-up be lost.
• Every row of the store carries its tenant and every query filters on it. A tenant of a shared deployment signs WorldSignalV2 (the signal names its tenant, environment, origin, link and key), so neither a token nor a signal of one tenant is accepted by another, even when two of them were (wrongly) given one key.
• Each instance bounds its open streams (streamsPerInstance, 10 000; then 429) and its per-connector minute: with N instances a connector may propose N times its quota.
• A stored row that no longer verifies is quarantined, never delivered, and doctor lists it.

Limit · bridge-tenants-demo-webhooks One server keeps one map of demonstration webhooks, by source, across all its tenants: two tenants with a webhook of the same source collide. Give the tenants of a shared server --no-demo-webhooks and one grant per connector.

Limit · bridge-tenants-shared-process The tenants of one server share its process, its CORS list (every tenant's --origin together) and its database. The isolation is the Bridge's code; there is no row-level security per tenant in Postgres, and a compromised instance holds every tenant's keys.

Common errors

Files or data changed

One folder per tenant (config.json, root.key, admin-token); the shared store, where every row carries its tenant.

Recovery or going back

• One tenant's rows, out of a shared store: tenant export --tenant=<id> --out=<file>; deleted: tenant delete --tenant=<id> --yes (Backup and restore).
• A tenant's key or root compromised, or an instance: Security. The other tenants are untouched by a tenant's rotation.

References

• The routing: bridge/src/server.ts; one tenant's configuration: bridge/src/config.ts; the stores: bridge/src/store-async.ts.
• ADR 0009, ADR 0010, the threat model docs/dev/threat-models/constellation.md.
• Tested by tests/bridge-tenancy.test.ts and tests/bridge-fanout.test.ts.

Edit the source of this page · Report an error