Moving a V1 server to V2

A server running Xema V1 becomes a V2 server in place: the same machine, its configuration, its agents, its call lists and its call history, carried across. V1 keeps answering calls until the last moment, and the only outage is the minutes between V1 stopping and V2 starting.

Before you start

• Pick a quiet hour. The switch itself takes a few minutes, and calls in progress then are dropped.
• Have root on the box.
• The server must run Ubuntu 24.04 or later; on an older release, upgrade the operating system first.

Install the new tooling

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

This only adds the xema command. Nothing of V1 is touched, and V1 keeps running.

See what it finds

sudo xema discover

It says what the machine runs — V1, here — and lists V1's services, its databases and the backups already on disk. It writes nothing. Read it before going further.

Rehearse it

sudo xema migrate --dry-run

The whole plan, step by step, and anything that would stop it. Nothing is changed.

Move it

sudo xema migrate

It finds the server's address on its local network and says which it took; a server on more than one network is asked which, or is told with --address <IP>.

In order, while V1 keeps answering calls:

1. takes the database login V1 already uses;
2. fetches every part of V2, without starting any of it;
3. records where V1's call history is;
4. takes a backup of V1 — every database, V1 itself with its binaries and settings, the phone system's configuration, the web server's — under /var/backups/xema/<time>/V1/;
5. converts V1's data into V2's: accounts, configuration, call lists, reports.

Each step that has already been done is found done and skipped, so you can take the backup yourself ahead of time (sudo xema backup) and the day itself is shorter; a run that stops partway finds the data it already converted done. A backup counts for twelve hours; an older one is taken again. If any step fails, the run stops there and V1 is still serving.

Then the switch:

6. stops V1;
7. begins carrying V1's call history, which is copied later, once V2 is running (see below);
8. makes the server a cluster of one, gives it its own passwords for the phone system, writes its files and starts V2.

V1's own tables and files are read and left exactly as they were.

A second V1 server

To add another V1 server to a cluster that is already running V2, join it as in clusters. It is backed up and V1 is stopped as above, but its accounts and call lists are not carried into the cluster; they stay on that server and in its backup. Its call history can be carried into an HA or DR copy kept on it, as in call record.

If it stops partway

Run the same command again. Every step checks what is already done; nothing is repeated and nothing is overwritten.

Going back

Everything V1 was is in the backup the run took:

ls /var/backups/xema/

The mariadb folder holds a dump of every database, and each archive beside it restores with tar -xzf <archive> -C /.

After the move

The server runs V2 from here on. A later V2 release arrives by sudo xema update (the xema command itself, whenever the channel's is newer) and then sudo xema upgrade (Xema's components and the release's database changes, within the installed version) — see upgrading. xema migrate is only ever for another version.

V1's call history is copied after the move, while V2 serves: sudo xema v1cdr migrate, as in call record.