Installation

OmniBus ships as a release archive (or the source tree). You install it onto a Linux host you control with a single script. The script is idempotent — re-run it any time to upgrade; your configuration is preserved.

Quickest path: the signed .run installer

OmniBus releases are published as one self-extracting, fully offline file per CPU architecture: omnibus-<version>-linux-x64.run and omnibus-<version>-linux-arm64.run, each with a .run.sig signature and a .run.sha256 checksum. A file bundles the application, a pinned Node.js runtime, the prebuilt production dependencies and the systemd packaging. The host needs no internet, no NodeSource, no npm registry, and no build toolchain:

sudo ./omnibus-<version>-linux-arm64.run                                  # default ports 80/443
sudo ./omnibus-<version>-linux-arm64.run -- --install -- --port 8080 --https-port 8443
./omnibus-<version>-linux-arm64.run -- --check                            # check this host only

Options after the second -- go to OmniBus's setup: --port N (80), --https-port N (443) and --skip-extras (no USB auto-mount or watchdog setup). With internet access, the same install is one line:

curl -fsSL https://updates.harnessautomation.com/install/omnibus.sh | sudo sh -s -- --port 80

What gets installed

• /opt/omnibus/releases/<version>/, with /opt/omnibus/current pointing at the running one (the previous one stays for rollback).
• /var/lib/omnibus: configuration, users, TLS and audit log; kept across upgrades and backed up before each one.
• /etc/omnibus/keyring.json: the Harness keys this unit trusts for updates.
• /usr/local/sbin/omnibus-update: apply FILE.run, verify FILE.run, status, rollback.

Updates

The unit checks updates.harnessautomation.com and shows new versions under System → Maintenance → Software update; an admin installs them (or turn on Install updates automatically). Sites without internet upload the .run and its .run.sig on the same page, or copy them over and run sudo omnibus-update apply omnibus-<version>-linux-<arch>.run.

Every update is verified against /etc/omnibus/keyring.json before anything runs, then installed beside the current release. The service restarts, and if the new version does not report healthy on /api/status the previous release and its configuration come back automatically.

A unit installed with the older install.sh or omnibus-installer-*.run is taken over by the first signed .run you install on it: the old /opt/omnibus is moved to /opt/omnibus.legacy-<date>, ports and other settings in omnibus.service.d/override.conf are kept, and the old install comes back if the new one fails its health check.

Building the .run yourself: npm run installer (harness-release build, configured by harness.release.json). Signing uses ~/Code/keys/omnibus-release-signing.pem; npm run release also publishes to the update server (HARNESS_PUBLISH_TOKEN).

The rest of this page describes installing from a source tree with install.sh, for development.

1. Get the release onto the host

Copy the OmniBus release directory to the target machine and cd into it. For example, over SSH:

scp -r omnibus-<version>/ user@host:~/
ssh user@host
cd ~/omnibus-<version>

The directory must contain install.sh and package.json.

2. Run the installer

sudo ./install.sh

That's the whole happy path. The installer will:

1. Preflight — confirm it's running as root on a systemd host, and detect your OS and CPU architecture.
2. Ensure Node.js 20.19+ — if Node is missing or too old on Debian/Ubuntu, it offers to install Node 22.x from NodeSource.
3. Build the application (npm install + npm run build) if a build isn't already present.
4. Deploy to /opt/omnibus and install production dependencies there.
5. Create the persistent data directory /var/lib/omnibus (mode 0750).
6. Install and start the hardened omnibus systemd unit. The service runs as root (required for privileged port binding, serial access, and the network management on the System page), so no dedicated service user is created and the install/data dirs are root-owned.
7. Health-check the running service and print the URL to open.

When it finishes you'll see something like:

OmniBus is installed.

  Open the web UI:
    http://omnibus.local/
    http://192.168.1.50/

Open that URL to begin First-Run Setup.

Installer options

Flag	Effect
-y, --yes	Non-interactive; assume "yes" to every prompt (good for automation).
--port N	HTTP port (default 80).
--https-port N	HTTPS port (default 443).
--no-build	Don't build; require a prebuilt dist/ (e.g. a packaged release).
--no-node-install	Never offer to auto-install Node.js.
--skip-extras	Skip optional single-board-computer extras (USB auto-mount, watchdog).
-h, --help	Show help and exit.

Advanced overrides via environment variables:

# Install to a custom location with a separate data directory:
sudo INSTALL_DIR=/srv/omnibus OMNIBUS_DATA_DIR=/srv/omnibus-data ./install.sh

# Run on high ports (no root binding needed at runtime):
sudo ./install.sh --port 8080 --https-port 8443

Non-default ports or paths are applied via a systemd drop-in at /etc/systemd/system/omnibus.service.d/override.conf so the shipped unit stays pristine across upgrades.

3. Operate the service

sudo systemctl status omnibus      # health
sudo journalctl -u omnibus -f      # live logs
sudo systemctl restart omnibus     # restart
sudo systemctl stop omnibus        # stop (won't auto-restart until started)

Upgrading

Drop the new release onto the host and re-run the installer:

cd ~/omnibus-<new-version>
sudo ./install.sh

/var/lib/omnibus (config, audit log, TLS material, users) is preserved. See Administration → Upgrades for a faster incremental deploy path for fleets.

Uninstalling

sudo ./uninstall.sh            # stop + remove app and unit; KEEP data
sudo ./uninstall.sh --purge    # also remove /var/lib/omnibus (and any legacy omnibus user)

--purge prompts before deleting the data directory.

Manual / other distributions

If you'd rather not use the script, or you're on a host without systemd:

npm run build
cd dist && npm ci --omit=dev
sudo PORT=80 node server.js

The build writes a lockfile alongside the bundle, so npm ci installs the exact dependency versions the release was built and tested against. (The installer does the same when it deploys.)

Binding to port 80 needs privilege. Either run with sudo, grant Node the capability once, or use a high port:

# Option A: grant the bind capability to node
sudo setcap 'cap_net_bind_service=+ep' "$(readlink -f "$(which node)")"

# Option B: just use a high port
PORT=8080 node server.js

Point OMNIBUS_DATA_DIR at a writable directory to control where config is stored.