Upgrading

A server install follows the branch it was installed from, main by default.

Before you upgrade

Back up. Migrations can’t be undone, so going back to older code needs the backup.
From the install directory, note the current commit, to roll back to:
```
sudo git rev-parse HEAD
```

Update a server install

From the install directory:

sudo ./manage.sh update --migrate
sudo ./sync-env.sh
sudo ./manage.sh check
sudo ./manage.sh restart

update --migrate stops the services, pulls the code, reinstalls the dependencies, rebuilds, applies pending migrations and starts the services again. When the install serves this manual, it rebuilds it too.
sync-env.sh adds the settings the new template.env has and .env lacks, showing the change before writing it.
check reports any setting still missing or invalid; fill it in .env.
restart loads the new settings.

When .env has an invalid setting, update still restarts every service, then exits with an error (fix).

If the update changed the nginx template, which sudo git diff --stat ORIG_HEAD HEAD -- deploy/nginx lists, render the site again:

sudo ./manage.sh nginx

If you edited tracked files that the update changes, update refuses to pull. Discard the edits or git stash them, then run update again.

Roll back

Take the commit you noted before upgrading.
If the update applied migrations, restore the backup taken before it; older code can’t use the migrated database.
Check out that commit and rebuild. --pulled skips the pull that would undo the checkout:
```
sudo git checkout <COMMIT>
sudo ./manage.sh update --pulled
```

To follow the branch again later, run sudo git checkout <BRANCH>, then sudo ./manage.sh update --migrate.

Update with Docker

git pull --recurse-submodules
docker compose up -d --build

The container applies new migrations and runs platforms import when it starts.

Upgrade notes

Steps a particular upgrade needs once, newest first.

Gateway client registry import (migration 019)

For installs from before 2026-10-07.

update --migrate applies migration 019, which imports data/gateway_clients/registry.json (or GATEWAY_CLIENTS_REGISTRY_FILE, if .env sets it). It logs the entries in mcc_mnc_overrides.json without importing them. Delete both files afterwards.

Adapter registry import

For installs from before 2026-10-06.

update --migrate and manage.sh migrate register adapter directories on disk that the database lacks, and move their settings and files out of the code. The Docker container does it at every start.

RelaySMS Publisher