Your first server

One server is a whole contact centre: it answers your numbers, runs your queues, serves the agents and keeps the recordings and the reporting. Most installations never need a second one.

What you need

• A machine running Ubuntu 24.04 or later — a cloud instance or one of your own.
• A number to call in on, from whichever carrier you use.
• Root on the box, and about ten minutes.

Install it

curl -fsSL https://www.xema.in/install-xema.sh | sudo bash

That puts the software on the machine and stops. It does not decide what the machine is for, and it does not switch anything on — those are yours, and they are the next two commands.

To follow the rolling build instead of the stable one:

curl -fsSL https://www.xema.in/install-xema.sh | sudo bash -s -- -d

Bring it up

sudo xema init

One command, for a server with nothing set up on it. It:

• sets up the database and a login for Xema, with a password nobody has to choose — recorded in /etc/xema, readable only by root;
• fetches every part of Xema this server will run;
• makes the server a cluster of one, named after the machine (--cluster <name> names it yourself), holding every role;
• gives the machine its own passwords for the phone system's control interfaces;
• starts everything, and restarts only what is running an older build or older settings.

It finds the server's address on its local network — how other servers would reach this one — leaving out VPN tunnels and Docker's bridges, and says which it took. A server on more than one network is asked which; --address <IP> answers in advance, and xema node address changes it later. --dry-run shows the whole plan and changes nothing.

If it stops partway, sudo xema node reset removes what it set up — keeping the databases, the credentials and the key ring — and sudo xema init can be run again.

Check it

xema status
xema discover

status shows what is running. discover shows everything the commands decide from — which version the machine runs, its databases, the cluster and the backups — and writes nothing.

Then open the admin pages in a browser at the machine's address, and add your first number, your first queue and your first agent.

Keep a backup

sudo xema backup

Every database, and the files that cannot be downloaded again — settings, the phone system's configuration, the web server's — in one folder per run under /var/backups/xema/, a folder inside it for each: mariadb, xema, asterisk, nginx, systemd. A file archive restores with tar -xzf <archive> -C /. Call recordings are not included; copy them separately.

To back up from the admin pages, on a daily schedule, and to download a backup, see backups.

When one server is not enough

Two reasons, and only two:

• More calls than one machine will carry. Adding a second server adds capacity to the same queues and the same reporting.
• Agents in more than one place, where each place should keep working on its own if the link between them goes down.

Both are the same next step: clusters and multiple sites.

Upgrading

sudo xema update
sudo xema upgrade

Three commands, and each does one thing:

• xema update replaces the xema command itself when the channel has a newer one — on any server, a V1 one included, since that xema is the tool that converts it.
• xema upgrade brings Xema's components and the release's schema changes, within the installed version.
• xema migrate is for another version — a V1 server becoming V2, and later V2 becoming V3.

Run update first: a release is applied by its own xema, and upgrade says so if this one is older. A xema that answers update with its list of commands is from before releases had version numbers, and cannot replace itself: run the installer once to replace it, then update and upgrade as above.

curl -fsSL https://www.xema.in/install-xema.sh | sudo bash

The installer only puts the xema command in place, and records which channel it was run for; it changes nothing else on the server. xema channel shows that channel, and xema channel set stable (or dev) changes it.

Each part of Xema has its own version number (2.0.412), and each release says which version of Xema it belongs to. upgrade refuses a release of another version rather than install it — that is migrate — while update only asks whether the channel's xema is newer. Both check every file they download and say what they change from and to. --dry-run lists it without changing anything, and xema status shows the version each part of Xema is on.

Preparing for the window

sudo xema update
sudo xema upgrade --prepare                 # within 12 hours of the window
sudo xema upgrade                           # in the window

--prepare does what can be done before the window and touches nothing that runs: on the server with the database it takes the backup the upgrade would take, and on every server it downloads and checks each part that changes and unpacks it beside the one it replaces. In the window, upgrade uses that backup while it is under 12 hours old, applies the release's schema changes, and stops each part, moves its prepared files into place and starts it, rather than unpacking it while it is stopped. What is written after the backup is not in it.

Preparing twice takes one backup: one under 12 hours old is used. --prepare --fresh-backup takes it again, for a window the last one would be too old for by the time it comes.

upgrade takes a backup on the server that holds the database, applies the release's changes to the database, then replaces what changed. A part that did not change is left running, and only the services that need it are restarted. On a cluster, upgrade the server with the database first; the others wait for it and say so. Your configuration, recordings and call history are left alone.

Sign-in keys, once. Manager, the BFF and Metrics sign and encrypt sign-ins with keys every server of the cluster shares. A server upgrading from a V2 that predates them stops before it changes anything and says what is missing. Make them on any one server, then copy the three files in /etc/xema (token-signing.pfx, token-encryption.pfx and token-clients.json) to every other one, readable by their owner alone:

sudo xema tokens create
sudo xema tokens secrets
sudo xema tokens            # the same thumbprints on every server

Then run sudo xema upgrade again. Every command, with its options, is in the command reference.

A server still running Xema V1 is a different step — see moving a V1 server to V2.