Sovereign Installation

This guide walks you through installing Novantra Sovereign on infrastructure that you control: a server in your data center, a VM in your private cloud, a Docker host, or a workstation for evaluation.

The installation is intentionally split into two parts:

1. Install the package - put Novantra onto the machine. This is a small, fast step that does not configure your product.
2. Run the first-run setup wizard - point your browser at the install and walk through 6 visible steps. This is where every real choice gets made.

Plan for the wizard to take about an hour the first time, including DNS, TLS, and license activation.

Before you start

Have the following ready before you begin. The installer itself is quick; the wait usually comes from one of these prerequisites not being in place.

A target machine

For evaluation, a small VM is fine. For production sizing, talk to your account team.

A PostgreSQL database

Pick one of:

• Bundled - the .deb and Docker packages can run an embedded PostgreSQL for you. Easiest. Good for a single-host install.
• Existing - point the install at your own PostgreSQL cluster. Recommended if you already have a managed Postgres in your environment. Must be PostgreSQL 15 or newer.

Have credentials and connection details ready before you start the wizard.

A license

You will need either:

• A signed license file issued by Novantra (offline activation path), or
• An activation code that lets the install pull its license from the Novantra control plane during setup (connected activation path).

A key provider

Sovereign refuses to bring up encryption against an unsafe default. You need to point it at a real key provider during the wizard. Choose one of:

• HashiCorp Vault with the Transit engine.
• A PKCS#11 HSM (network or on-host).
• AWS KMS or Azure Key Vault (if you choose to back Sovereign with a cloud KMS even though the install itself is on-prem).

Have the endpoint, the credential, and the key/keyring identifier ready.

A planned admin URL

This is the URL administrators will use to reach the system console (where you manage organizations, licensing, mail settings, and so on). For example, https://manage.novantra.acme.internal. You will set this in the wizard.

You don’t need to have DNS in place to start the wizard (the wizard opens on a local URL), but you will need DNS and TLS sorted before administrators can use the admin URL from their own machines. See Access URLs for the full custody story around URLs.

A reverse proxy plan (recommended)

The recommended TLS setup is to run nginx, HAProxy, or your ingress controller in front of Novantra. Your existing certificate process keeps working unchanged. You can also let Novantra terminate TLS directly if you prefer, in which case you’ll be prompted for a certificate path during the wizard.

Mail (optional but recommended)

If you want admin email verification, password reset, invitation emails, and notifications to work, have SMTP details ready. You can skip mail at install time and add it later.

Pick and install the package

Docker

Pull the image and run it. Mount a volume for state, expose the setup port:

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

The container starts and immediately exposes the first-run setup wizard on port 7443. The first time it boots, it generates a one-time setup token and writes the full setup URL (including the token) to /var/lib/novantra/onprem/setup-url.txt. Read it with:

docker exec novantra cat /var/lib/novantra/onprem/setup-url.txt

Open the URL in your browser.

Ubuntu .deb

Install the package with apt or dpkg. The package installs a systemd service and an editable bootstrap config at /etc/novantra/bootstrap.env. The service runs under a restricted novantra user.

Once installed, the service listens on 127.0.0.1:7443 by default. Find the setup URL with:

sudo cat /var/lib/novantra/onprem/setup-url.txt

If you need to reach the wizard from another machine, edit /etc/novantra/bootstrap.env to change the bind address (see Binding the setup wizard to your network below), restart the service, and re-read the URL.

Windows MSI

Run the MSI. It installs Novantra as a Windows service and creates a desktop shortcut that opens the local setup URL. The shortcut contains the one-time setup token so you don’t have to copy it around.

The wizard binds to 127.0.0.1:7443 by default, so the shortcut only works from the local machine. To open the wizard remotely, see below.

Binding the setup wizard to your network

By default, MSI and .deb installs bind the wizard to 127.0.0.1. That keeps it inaccessible from anywhere except the install host while the system is in its most vulnerable state. To open it to a LAN or VPN address, set:

• ONPREM_SETUP_BIND_ADDRESS=0.0.0.0 (or a specific interface IP)
• ONPREM_SETUP_PORT=7443 (or your chosen port)

in /etc/novantra/bootstrap.env (Linux) or the equivalent Windows config, then restart the service.

If you need a fresh token (for example you closed the browser before saving the URL), run:

novantra setup-token rotate

The new token replaces the old one. The previous URL stops working immediately.

Walk through the setup wizard

Open the setup URL in your browser. The wizard saves your progress, so you can stop and resume each step.

Step 1 - Welcome

The wizard confirms:

• The package version installed on this host.
• The deployment profile (default or no-training - this was set by the installer; you don’t choose here).
• That the install package itself is sane.

There is nothing to enter. Click Continue.

Step 2 - License

Choose one of the activation paths:

Connected activation. Paste an activation code or sign in through the control-plane portal. The install reaches out to Novantra, validates your license, and pulls the signed license file. Requires outbound HTTPS to the control plane.

Offline activation. Upload a signed license file you already received from Novantra. No internet connection from the install is needed. You will still need to come back later (from any internet-connected machine) to refresh the license when you add organizations - the wizard covers that flow when you get there.

The wizard validates the license signature, checks validity windows, and shows you what apps and capabilities the license includes. No organization entitlements are projected yet - that happens later when you actually create your first organization.

Step 3 - Database

Pick one:

• Bundled PostgreSQL (where available) - the installer manages a Postgres service for you on the same host. Easiest, no external dependencies.
• Existing PostgreSQL - paste a connection string for your own Postgres cluster.

The wizard tests the connection, then runs the deployment migrations. Migrations are explicit - you see them happen, you see them succeed, you don’t move on until they’re clean.

Step 4 - Key provider

This is where you wire Sovereign into the encryption infrastructure you brought.

Pick your provider (Vault Transit, PKCS#11 HSM, AWS KMS, or Azure Key Vault), enter the endpoint, credential, and key/keyring identifier. The wizard runs a verification probe against the provider - confirming it can reach the key and perform the operations needed - and shows you a sanitized result.

The wizard will then create your install keyring. This is the root of trust for everything Sovereign encrypts at the install level. The active key is warmed immediately so the rest of setup can use it.

Step 5 - Install settings

Configure how the install presents itself to administrators:

• Display name - what shows in the title bar and admin emails (for example, “Acme Corp Novantra”).
• Admin URL - the URL administrators will use, for example https://manage.novantra.acme.internal. This is what your DNS should point at.
• Mailer - SMTP settings, or “configure later” if you want to skip. Without mail, password resets and admin email verification do not work.
• TLS - if Novantra is terminating TLS directly, point it at a certificate and key. If you’re running a reverse proxy in front (recommended), leave TLS off here and let the proxy handle it.

Step 6 - First admin

Create the first install-administrator account:

• Name, email, password, locale.
• MFA enrollment is mandatory before this step can complete. You’ll scan a TOTP QR code (Google Authenticator, 1Password, Authy, etc.) and confirm a one-time code.
• If you configured mail in the previous step, email verification is also required.

When this step completes, the wizard hands you off to the admin shell. The setup token retires automatically. The /setup URL is closed. There is no way back into the wizard from here.

After setup

You are now signed in to the system console as the first install-administrator. From here you can:

1. Create your first organization. This runs a separate, gated wizard. For connected installs, the wizard talks to the control plane to confirm payment/plan, then issues a refreshed license that names your new organization. For offline installs, the wizard generates an activation request file that you carry to an internet-connected machine; the control plane returns a refreshed license you upload back.
2. Set the access URLs for that organization. Workspace URL and public URL - see Access URLs.
3. Configure storage for that organization, if you want it on customer-owned storage from day one - see Self Managed Storage.
4. Wire BYOK if the organization needs customer-held encryption keys - see Self Managed Secret Keys.

Each of these is a deliberate, evidence-producing change with audit trails. None of them happen by accident.

Where install state lives

For routine operations, you don’t need to touch the filesystem - the admin shell exposes everything. But it’s useful to know:

• /etc/novantra/bootstrap.env (Linux) - editable bootstrap config (bind address, setup port, paths).
• /var/lib/novantra/onprem/ - persistent install state, including bootstrap state, setup-secrets, and the setup URL file before setup completes.
• Logs go to your system journal (journalctl -u novantra on systemd; Event Viewer on Windows; docker logs novantra in Docker).

Updates

Connected installs receive update hints from the control plane (current available version, security advisories). The control plane never pushes binaries to your install.

To apply an update:

• Docker: pull the new image tag, stop the running container, start a new one against the same volume mount. State persists in the volume.
• Ubuntu: apt upgrade the package. The service restarts.
• Windows: run the new MSI. The service restarts.

Migrations needed by the new version run on the next service start. The migration composer makes the same explicit, observable migration step you saw during initial setup, but for upgrades.

Offline installs check for new versions whenever you fetch a fresh license. Download the new artifact through your usual provisioning channel and apply it the same way.

Troubleshooting

The setup URL says “setup is complete.” Setup ran once and finished. The setup token has been retired. Sign in through the admin URL with your first-admin credentials instead. If you genuinely need to re-do setup, that is a reinstallation, not a wizard retry.

I lost the setup token before finishing. Run novantra setup-token rotate on the install host. A new token is generated; the old one stops working immediately. Re-read the setup URL file.

License preflight fails. The most common cause is a clock-skew issue: signed licenses have validity windows, and a host clock that is hours off rejects valid licenses. Make sure the install host’s clock is correct (use NTP) and retry.

Key provider verification fails. The wizard returns a sanitized reason. The most common causes are missing permissions for the principal you configured, an unreachable endpoint (firewall, private link, DNS), or a key identifier that doesn’t exist. Fix on your side, then retry verification in the same wizard step.

Database migrations stall. Check the connection has the privileges to create schemas and tables. The wizard shows which migration is running; logs from your Postgres show what it tried.

Related

• Access URLs - planning the workspace URL and public URL for each organization you create.
• Self Managed Storage - turning on customer-owned storage for an organization.
• Self Managed Secret Keys - holding the encryption keys for an organization in your own KMS.