Upgrades and backups

Upgrading

Knowing there is one

The Nodes tab says when a newer release is out: each central server checks Routes’ public releases once a day (Settings › Check daily for a newer release; nothing is sent but the request). It also shows each node’s version, marks nodes that run another version than the central service, and an alert is raised when one still does after an hour. Release notes and downloads are on the download page.

The order: central servers first, then nodes

The central servers, one at a time if you have several: nodes keep routing meanwhile, with the configuration they have, and send their history once the central service is back. The database schema is updated by the first one to start.
- Windows: run the newer Routes.Central.msi (or msiexec /i Routes.Central.msi /qn). Every setting is kept: the installer reads them back from the registry.
- Linux: stop the service, replace /opt/routes/central with the new package’s routes-central folder, start it.
- Docker: set TAG in .env to the new version (or use the new release’s Docker kit), then docker compose pull and docker compose up -d central; the nodes after, with docker compose up -d.
Then each node, one at a time: Drain it on the Nodes tab, wait for Drained, install the new version as above, then Resume. With a load balancer, senders go to the other nodes meanwhile. With a single node there is a short gap while it restarts: senders retry, or queue on their side, as for any destination that is briefly away; what the node had already received waits on its disk.

The central service always works with nodes one release behind, so there is no hurry to update every node at once, and a node that is offline during the update catches up later. (Nodes newer than the central service are not supported: update the central servers first.)

Updating nodes with a script

Update-RoutesNode.ps1 (Windows) and update-routes-node.sh (Linux), from the release’s downloads, do a node’s whole update unattended: drain it, wait until it has nothing in progress, install, wait for it to report in on the new version, resume it.

Make an API token: Configuration › Node enrollment › API tokens, Make a token. It can see nodes and drain or resume them, nothing else. Copy it: it is shown once.
On each node in turn, as an administrator (root on Linux):
Terminal window
```
$env:ROUTES_API_TOKEN = 'rt_…'
.\Update-RoutesNode.ps1 -Msi .\Routes.Node.msi
```
Terminal window
```
export ROUTES_API_TOKEN=rt_…
sudo -E ./update-routes-node.sh routes-node-<version>-linux-x64.tar.gz
```
They read the central service’s address, the node’s name and the central certificate’s thumbprints from the node’s own settings (registry, or /etc/routes/node.env); -Central, -Node and -CentralThumbprint (--central, --node, --thumbprint) override them.

Draining waits up to 30 minutes (-DrainMinutes) for Drained. If instances are still queued then (a destination is down, say) but nothing is being received, the update goes ahead: queued instances stay on disk and are sent after it.
If the installation fails, the node, still on its old version, is resumed and the script fails.
If the node does not come back on the new version within 10 minutes (-StartMinutes): on Windows it is left drained for someone to look at; on Linux the previous version (kept in /opt/routes/node.previous) is put back and resumed.
The scripts refuse to install a version newer than the central service’s. -WhatIf (--what-if) shows what would happen without changing anything.

Run them from a scheduler, a configuration management tool (Ansible, SCCM, Intune) or by hand; one node at a time, so that the others keep taking traffic.

What to back up

What	Why	How
The database	The configuration and its history, the encrypted secrets, the instance and HL7 history, the audit log.	Nightly full backups plus log backups (SQL Server), or `pg_dump` / continuous archiving (PostgreSQL).
The secret protection key	Without it, the database’s secrets cannot be read.	On Linux and Docker, and with `SecretProtection=Certificate`: `secret-protection.pfx` in the central data folder. On Windows with `Machine` or `Account`, it is in Windows; see below.
The configuration export	A readable copy you can import into a new installation.	After significant changes: Configuration › Import / export › Export.

Nodes need no backup: their data folder holds only what is in transit. Use redundant storage if instances must survive a disk failure before they are delivered.

Restoring to another server

The configuration and history come back with the database. The secrets come back only if the new server can read them:

Machine (one Windows central server): a new server cannot. Re-enter the SMTP password, the webhook and DICOMweb credentials, and generate a new enrollment key; enrolled nodes keep working. The de-identification keys cannot be read either: where pseudonyms must stay the same over time, use Account or Certificate protection, so that a restore keeps them.
Account or a group descriptor: a server running as the same account (or group) can.
Certificate: restore secret-protection.pfx with the database.
HashiCorpVault or AzureKeyVault: a server with access to the same vault and key can (keep the vault’s key, and its old versions, as long as the database and its backups).

Configuration only

Configuration › Version history keeps a copy of the configuration after every change, for a year and at least the last 200 changes. Any version can be compared, exported or restored, so a bad change is undone in seconds without touching the database backups.