Files

T

wmantly 455450db1f feat(multi-site): spoke.env.example + CFG_PUBLIC_DOMAIN

A dedicated spoke.env for the join-a-cluster vars (CFG_MASTER_DIRECTORY_URL/
_JOIN_KEY, CFG_SPOKE_NO_INBOUND/_PUBLIC_HOST, CFG_PUBLIC_DOMAIN), split out
of setup.env purely for clarity -- setup.env still has every option and
keeps working as a single file if that's preferred. setup.sh reads both
(setup.env first, spoke.env layered on top so its values win), same
first-run-only rule as setup.env already had.

Also adds CFG_PUBLIC_DOMAIN (documented in MULTI_SITE_SPEC.md §4 but never
actually wired into setup.sh): an inbound spoke/standalone site's own public
web domain, independent of CFG_DOMAIN (the shared LDAP identity namespace,
which must stay identical across every site). Unset behaves exactly as
before -- hostnames derive from CFG_DOMAIN like any standalone install.

2026-08-10 22:22:54 -04:00

5.7 KiB

Raw Blame History

layout, title

layout	title
default	Multi-Site (Master/Spoke Join)

Multi-Site (Master/Spoke Join)

If you run more than one physical site, Theta Directory can run one site as the master (single write authority for the shared catalog) and any number of spokes — read-only replicas that stay in sync automatically and run local authentication with zero WAN dependency.

This is a different, higher-level mechanism than raw LDAP N-way replication — see How this relates to LDAP replication below if you're deciding between the two.

Why and when to use this

Zero-touch spoke setup. One join key, one URL, and a spoke adopts the whole directory (users, groups, resource catalog) in one step — no manual syncrepl configuration.
Single write authority, no split-brain. Only the master accepts directory writes. A spoke that loses WAN connectivity keeps working for local reads/auth and unconditionally stays read-only — it never silently promotes itself. Changing which site is master always requires an explicit, authenticated action by a god_admin.
Stays in sync, not just a one-time copy. Once joined, a spoke keeps receiving live updates whenever the master's catalog changes — you don't re-run the join to pick up new hosts/apps/users.

How it works

On the master, an admin mints a site join key (Directory → the Master Site modal → Site Join Keys → Mint key). It's shown once, stored hashed, and revocable.
On the spoke (must be a fresh install — no users beyond the bootstrap admin, no enrolled agents), either:
- Paste the master's URL and the join key into the Master Site modal's Join an Existing Site form, or
- Set CFG_MASTER_DIRECTORY_URL / CFG_MASTER_DIRECTORY_JOIN_KEY before the first ./setup.sh run -- either in setup.env (which has every option), or in a dedicated spoke.env (cp spoke.env.example spoke.env) if you'd rather keep join-a-cluster config separate from the rest of the stack's setup. Both are read; spoke.env's values win on a conflict. No public IP on this site at all? spoke.env.example also covers the no-inbound relay vars (CFG_SPOKE_NO_INBOUND/CFG_SPOKE_PUBLIC_HOST).
The spoke pulls the master's full export (LDAP tree, resource catalog, agent-signing key) and adopts it, then registers its own reachable URL with the master so it can receive live updates going forward.
From then on, every change to the master's catalog pushes to every registered spoke automatically. A spoke's own directory-write requests are rejected with a 403 pointing at the master — writes always go there.

Promoting a spoke to master

If the master site goes down for good (or you're relocating write authority), a god_admin can promote any spoke from its own Master Site modal. Promotion is one coordinated action: it demotes the previous master as part of the same request (best-effort — an unreachable old master never blocks the promotion, since that's exactly the scenario this exists for), and every other spoke gets pointed at the new master automatically.

What replicates

Data	How
LDAP (users, groups)	Full export on join; live push on every master change
Resource catalog (hosts, apps, sites)	Same
Agent-signing key	Same — every site can validly sign a command for any agent enrolled at any site

The agent-signing key being identical everywhere is a deliberate tradeoff for small, trusted deployments (a handful of sites, not hundreds) — it means compromising the least-secured spoke has the same agent-command blast radius as compromising the master. If that tradeoff doesn't fit your deployment, don't rely on this mechanism as-is.

Secrets beyond the agent-signing key (LDAP admin password, JWT secret, and so on) are not currently synced — each site still generates its own.

Requirements and current limits

Both sites need a network path to each other's HTTP(S) API — the master to pull an export from, the spoke to push replication updates back to. A site with no inbound path at all (e.g. behind CGNAT) can't join yet on its own; a relay mechanism for that case is designed but not automated (see the architecture spec for the current status).
Joining only ever happens on a fresh install. There's no way to merge an already-populated directory into a master's — re-provision the host first.

How this relates to LDAP replication

N-way LDAP replication is a lower-level, different mechanism: every site runs a fully independent, fully writable slapd, wired together with raw syncrepl environment variables, and there's no concept of a master or a managed join. It predates this feature and is still there for deployments that specifically want every site independently writable.

Multi-site join (this page) is the opposite design: one write authority, a managed onboarding flow, and automatic ongoing sync — closer to what most "add a second office" or "add a home-lab spoke" setups actually want. Don't combine the two — pick one per deployment.

5.7 KiB Raw Blame History