Deployment models

Four shapes cover almost every Xema installation. Pick the one that matches what you are building; each says what it gives you, what it does not, and the exact commands.

Two words, used precisely throughout:

A site is servers in one place working as one contact centre. They share a database, a broker and one pool of agents. A call arriving at any of them can be answered by an agent signed in at any other.
A cluster is one or more sites. Sites may be a thousand kilometres apart, and each keeps working when cut off from the others. Only asynchronous copying crosses between them — never a lock, never a query that waits.

	Shape	Gives you	Does not give you
A	One server	The whole contact centre, simply	Any redundancy
B	Two sites, one server each	Two independent locations	Shared capacity; either site's redundancy
C	One site, three servers	Capacity, one agent pool, room to lose a server	Redundancy of the shared parts, unless you add it
D	Two sites, three servers each	Both of the above, in two locations	Anything if the shared parts of a site all sit on one machine

A — One server

The ordinary deployment. It holds every role: the database, the broker, Redis, Asterisk and every Xema service. Nothing about it is a compromise, and nothing below is required to run a real contact centre.

There is no redundancy. If the machine fails, the contact centre stops.

curl -fsSL https://www.xema.in/install-xema.sh | sudo bash
sudo xema connect-database --server localhost --user xema --provision
xema cluster init --site main

That is the whole of it. cluster init is worth running even here — it gives the server a real cluster and site identity rather than an implied one, so the day a second server appears is not the day everything has to be re-identified.

C — One site, three servers

The one to reach for when one machine is not enough. Read this before B, because a second site is a bigger step than a second server and is usually not what people mean.

What it gives you:

Capacity — more concurrent calls and agents than one machine carries
One agent pool — a call arriving anywhere can be answered by an agent signed in anywhere, so agents are not divided up by which server they happened to reach
Room to lose a server — one that holds none of the shared parts can fail without stopping the site

What it does not give you, and this is the part most often assumed:

The site still has one database, one broker and one Redis. If they all sit on the server that fails, the site stops — with three servers as surely as with one.

Real redundancy of those is a separate exercise: Galera or InnoDB Cluster for MariaDB, Redis Sentinel, quorum queues for RabbitMQ. It belongs inside a site and never across sites, because each of those is designed to stop when it loses quorum. Nothing in the install sets it up.

Decide before you start: which server is the database, which is the broker, which is Redis (they may be one machine), and which trunk is plugged into which server.

Full steps are in CLUSTER.md. In outline:

# On the first server — this one becomes the site
sudo xema connect-database --server localhost --user xema --provision
xema cluster init --site alpha
xema site secret set redis --generate
xema site secret set broker --username xema
xema site secret set node --generate          # without this, calls cannot cross servers
xema cluster token                            # a single-use pass

# On each of the other two
xema cluster join --token <pass>
xema role add bff && xema role add queue      # whatever that server is for
xema node apply
xema node wire && sudo xema restart all

Then, in the console, set Connected to node on every trunk. A trunk nobody has assigned is carried by no server at all, and calls on it do not arrive.

B — Two sites, one server each

Two independent contact centres that share configuration and report as one. Each site answers its own calls with its own agents, and keeps working when the link between them is down.

Use it for two offices, or a primary and a disaster-recovery location.

What it gives you:

Each location survives losing the other entirely
One set of configuration and one place to report from

What it does not give you:

Shared capacity. Cross-site help is a bonus, never a guarantee — when the link is down, the other site's agents are genuinely unavailable and calls fall back to local ones.
Redundancy within either site. Each is still one server; see A.

Not yet possible with the shipped commands

There is no way to add a second site to an existing cluster. Running xema cluster init --site beta on the second server creates a brand-new cluster, not a second site of the first — so the two do not know about each other.

Missing: a site init / site join pair, and the asynchronous copying between sites' databases. Until then, build each location as model A and treat them as unrelated.

D — Two sites, three servers each

A large deployment in two locations. Model C twice over, federated as in model B — so each location has capacity and an agent pool of its own, and either survives losing the other.

Everything in C applies to each site separately, including that a site's shared parts are still one database, one broker and one Redis unless you deliberately make them redundant.

Not yet possible with the shipped commands

Same reason as B: a cluster cannot yet hold a second site. Each location can be built today as model C; joining them into one cluster is what is missing.

Choosing

Start at A. Move to C when one machine is not enough — that is a change of size, and the commands are a superset of A's.

Move to B or D only when you have two locations, because that is what a second site is for. Two sites in one building is the wrong shape: it splits the agent pool for nothing and gives up the shared capacity that C is for.

And at every size, the question worth asking early is the one none of these models answers by itself: which single machine must not fail? In A it is the only one. In C and D it is whichever holds the database, the broker and Redis — until somebody makes those redundant on purpose.