Updates & Upgrades

Once a Sovereign install is running, you keep it current by applying new versions of the Novantra package. The packaging is the same in shape as the initial install (Docker, Ubuntu .deb, Windows MSI), but you’re laying a new version over an existing data set.

The good news: data and state always live outside the package. Updates swap the binaries; your data, settings, license, and key material persist where they always lived.

Before you update

A small checklist:

1. Take a fresh backup. Always. See Backup & Restore for what to capture.
2. Read the release notes. Each version comes with notes describing migrations, any change in supported platforms, and any operational steps required before or after the upgrade.
3. Check your license has at least a few weeks of validity left. Updates don’t change your license, but a license lapsing during an upgrade window adds noise.
4. Schedule a window. Updates require a short restart and migration window. Plan for it.

Release channels

Novantra publishes Sovereign artifacts on two channels:

• Stable — production-ready releases. Most installs should run only stable.
• Preview — early access for customers who want to validate against their environment before stable cuts. Treat as not-for-production.

The channel you’re on is decided by which artifact you download, not by a setting inside the install.

Deployment profiles

Each version is built in two profiles that exclude or include different code paths:

Stick with the profile you started with. The profile is baked into the artifact name; you won’t accidentally mix.

Applying the update — Docker

docker pull novantra/onprem:<new-version>
docker stop novantra
docker rm novantra
docker run -d \
  -v /var/lib/novantra/onprem:/var/lib/novantra/onprem \
  -p 7443:7443 \
  --name novantra \
  novantra/onprem:<new-version>

The data volume persists across the swap. The new container picks up the existing license, install state, and configuration on first boot.

Applying the update — Ubuntu .deb

sudo apt update
sudo apt install --only-upgrade novantra

The package’s post-install hook restarts the novantra systemd service. Logs from the restart:

journalctl -u novantra -f

The package is intentionally thin: the install hook does not run migrations, does not touch the license, and does not modify your reverse proxy or firewall. All real upgrade work happens when the service starts.

Applying the update — Windows MSI

Run the new MSI. The installer detects the existing install, stops the Novantra service, replaces the binaries, and starts the service back up. State under the Novantra data directory is preserved.

What happens on first start after an update

On every start, the install:

1. Verifies the package signature before doing anything else. An unsigned or tampered package refuses to start.
2. Runs deployment migrations that the new version needs. This is an explicit, observable step — you see each migration in the log as it executes, and the install does not begin serving traffic until they finish.
3. Re-verifies the license signature against the new binary’s release key.
4. Re-warms the install keyring through whichever key provider is configured.
5. Starts the HTTP server and begins serving.

If migrations fail, the install stops and reports the failing migration in the log. The system never partially-migrates and proceeds anyway — that would risk silent data corruption.

Rollback

The general rule: you can roll back before any migration in the new version has run. After a successful migration, the database schema is on the new version’s shape, and the old version will fail to start against it.

To roll back safely:

• Always roll back from a backup taken before the upgrade if you’ve already let migrations run. Reinstall the previous version, then restore the backup.
• Before migrations run, you can just reinstall the previous package and start it again — the data is unchanged.

This is why the pre-update backup matters.

Skipping versions

The general expectation is that you can update from any recent supported version to the latest. Migrations are written to be cumulative — a new install picks up everything; an in-place upgrade picks up only the new ones.

That said, very large jumps (more than two major versions) may not be supported in a single hop. Release notes spell out the supported source-version range for any given release. If you’re far behind, expect to stage the upgrade through one or two intermediate versions.

Connected installs: update hints

If your install reaches the control plane, the Operations page in the system console shows:

• The version you’re currently running.
• The latest stable version available for your channel.
• Any security advisories tied to your version.

These are hints, not auto-installations. Novantra does not push binaries to your install. You decide when to apply.

Offline installs: update flow

Offline installs do not see update hints from inside the product. Operators typically:

1. Download new artifacts through their usual provisioning channel (USB, signed mirror, etc.).
2. Verify checksums and signatures locally against the published values.
3. Apply the new package using one of the format-specific procedures above.

The same backup-first, watch-the-migrations rules apply.

After the update

Things to check once the service is back up:

• System → Operations — confirm health probes show green.
• System → License — confirm the license is still recognized.
• System → Investigations — review the audit chain for the migration window; you should see the upgrade actions recorded.
• A quick sign-in to any organization to confirm member-facing flows work end to end.

If anything looks wrong, the migration log and the system journal are your first port of call.

What never changes during an update

A short list of things that are not touched by an update:

• Your data.
• Your license file.
• Your install keyring or any keys held in your KMS.
• Your mailer, storage binding, or organization access URL settings.
• Your reverse proxy and certificates.

If any of these need to change as part of an upgrade, the release notes call it out and provide migration instructions explicitly. Quiet, undocumented breaking changes are not a thing here.

Related

• Backup & Restore — take a backup before every upgrade.
• License Management — license validity is independent of version.
• Health & Monitoring — what to watch right after a restart.