Skip to content

Headless Installation

On a Linux server without a desktop, you can run the OnVeris installer from the command line. It does everything the installer window does — install, update, start and stop, access keys, the firewall and support logs — and never needs a display.

Note

This page is for Linux. On Windows and macOS, and on Linux machines with a desktop, use the installer window described in Installing OnVeris.

Download The Installer

Download the OnVeris installer for Linux from onveris.com/download, choosing x86-64 or ARM64 to match the server, and copy it to the server. Then make it executable:

chmod +x OnVerisInstaller

Install

Run the installer with sudo, and say what to install with --gateway, --node, or both.

For example, to install the Gateway and Node on this server:

sudo ./OnVerisInstaller install --gateway --node

The installer will show each step as it runs, then a summary of what is running, its address and its firewall status.

Option What it does
--gateway Install the Gateway
--node Install a Node
--access-key KEY Set the access key once installed. Use it when installing a Node for a Gateway on another machine
--no-firewall Leave the firewall alone. Without it, the installer opens the ports in ufw or firewalld if one is active, as described in Firewall
--prerelease Install the latest pre-release build. Use only if Parker Software support asks you to

If a port that OnVeris needs is already in use, the installer will warn you before it starts. The component will not start until the port is free.

The first install also places a copy of the installer at /opt/OnVerisInstaller/OnVerisInstaller. Use that copy for everything afterwards:

sudo /opt/OnVerisInstaller/OnVerisInstaller status

Note

On a machine first installed as Optima, the copy is at /opt/OptimaInstaller/OptimaInstaller. See Machines First Installed As Optima.

Installing A Node For Another Gateway

A Node only accepts a Gateway that uses the same access key. Copy the Gateway's key first — on the Gateway machine, it is on the Gateway's card in the installer's Manage page, or shown by access-key show --gateway there. Then install the Node with it:

sudo ./OnVerisInstaller install --node --access-key 3f2a9c1e-77b4-4d0a-9b1e-5c2d8e6f1a42

If you install a Node without --access-key, the summary will end with an IMPORTANT — ACCESS KEY section showing the Node's own key, and how to set the Gateway's key instead.

After Installing The Gateway

Open the Gateway's address, shown in the summary, in a web browser on another machine. You will be taken through the first-time setup. See First-Time Setup.

Managing OnVeris From The Command Line

Every command except status needs sudo. Commands other than install and uninstall act on whatever is installed, unless you name --gateway or --node.

Command What it does
status Shows each component's version, whether it is running, its address, whether its access key is set, and its firewall status. Add --json for output a script can read
start, stop, restart Start, stop or restart the services. Starting checks that the service is still running a few seconds later
access-key show Shows the access keys
access-key set KEY Sets an access key. The component will restart to use it
access-key generate Creates a new access key, sets it, and shows it
firewall status Shows whether other machines can reach each component
firewall allow Opens the firewall for each component, if it needs it
update Updates to the latest version. If the new version will not start, the previous version is put back
uninstall Removes the components you name with --gateway or --node. Add --remove-data to delete their data too
collect-logs Creates a zip file of logs for Parker Software support, in the current folder or the one given with --out
help Lists the commands and options

For example, to give the Gateway and the Node on this server a new access key:

sudo /opt/OnVerisInstaller/OnVerisInstaller access-key generate

Changing the Gateway's key disconnects every Node on other machines until they are given the same key. See Access Keys.

Warning

uninstall --remove-data deletes the Gateway's conversations, users and Knowledge Bases, and the Node's settings and downloaded models. It cannot be undone. See Back Up And Move OnVeris.

Exit Codes

The installer returns an exit code that a script can check:

Code Meaning
0 Success
1 The command failed. The reason is written to the terminal
2 The command or its options were not recognised
3 The command needs sudo

The Services

The installer registers the Gateway and Node as systemd services named OnVerisGateway and OnVerisNode. You can also check them with systemd directly:

sudo systemctl status OnVerisGateway
sudo systemctl status OnVerisNode

Service names in systemd are case sensitive.

Note

On a machine first installed as Optima, the services are named OptimaGateway and OptimaNode. See Machines First Installed As Optima.