rs2 / restspace

10.2 Single- vs. multi-tenant deployments

A node serves either one tenant or many. The choice is in serverConfig.json's tenancy block and changes how each request is mapped to a tenant — everything else (mounts, services, isolation) is the same.

Single-tenant

"tenancy": { "mode": "single", "tenant": "main" }

Every request belongs to the named tenant. The simplest mode — use it for a single app, local development, or a dedicated per-customer node.

Multi-tenant

"tenancy": {
  "mode": "multi",
  "domainMap": { "api.acme.com": "acme", "app.example.com": "example" },
  "mainDomain": "rs2.example.com"
}

The tenant is resolved from the request's Host header, in two steps:

  1. Explicit domain map — an exact host match wins (api.acme.com → acme).
  2. Subdomain rule — otherwise {tenant}.{mainDomain} is parsed, so acme.rs2.example.com → acme.

The domain map is checked first, so you can give a tenant a vanity domain and still fall back to subdomains for the rest.

Isolation holds either way

Whichever mode, tenants are fully isolated: separate file/data storage (prefixed under fileRoot), separate config, separate users, separate resource budgets and circuit breaker (9.5). A custom service in one tenant can't reach another tenant's data — the capability scoping and path safety are per-tenant by construction.

Operational notes

  • Lazy loading — a tenant config is built the first time its host is addressed, so adding a tenant is just dropping a <tenant>.json in tenantsDir (and reloading, or having it loaded on first hit).
  • Per-tenant logs — the default file sink writes one NDJSON file per tenant (10.3), so logs are naturally separated.
  • Node-local state caveat — session/lockout state is currently node-local (5.3); for multi-node multi-tenant deployments behind a load balancer, be aware that counter sharing across nodes is a tracked future item.

Choosing

  • One app or one customer → single.
  • A SaaS serving many customers from one node → multi, with subdomains and/or vanity domains via the map.

Next: where logs go and how to read them back.

← Previous: 10.1 Server config in depth · Manual home · Next: 10.3 Logging & observability →