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 offline .run installer

For field deployment, OmniBus is also published as a single self-extracting, fully offline file, omnibus-installer-<version>.run. It bundles the prebuilt application, a pinned Node.js runtime (one binary per CPU architecture), the prebuilt production dependencies, the installer, and the systemd packaging into one executable. The target host needs no internet, no NodeSource, no npm registry, and no build toolchain — drop the file on the host and run it:

sudo ./omnibus-installer-<version>.run                      # default ports 80/443
sudo ./omnibus-installer-<version>.run -- --port 8080       # forward installer flags

Everything after -- is passed straight to install.sh (see Installer options). On a host with internet you can still use it — it simply skips the download steps it doesn't need. The archive also understands a few self-extractor options of its own, useful before you commit to installing:

./omnibus-installer-<version>.run --check                   # verify SHA256 + MD5
./omnibus-installer-<version>.run --info                    # show build metadata
./omnibus-installer-<version>.run --list                    # list bundled files
./omnibus-installer-<version>.run --noexec --target DIR     # extract without running

When it runs, install.sh detects the bundled assets, selects the Node binary matching the host's CPU (uname -m), installs it under /opt/omnibus/node, copies the bundled dependencies into place, and configures the service to run from that runtime via a systemd ExecStart override — so the unit never depends on a system Node. The rest of this page describes the equivalent steps when installing from a release directory or the source tree (which do use the network for Node and dependencies).

Building the .run yourself: npm run installer bundles dist/ + install.sh + a SHA256-verified Node runtime + dependencies with makeself. OFFLINE=0 builds a smaller online-only wrapper; TARGET_ARCHES and NODE_VERSION tune the bundled runtimes. See scripts/make-installer.sh.

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 18+ — 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 install --omit=dev
sudo PORT=80 node server.js

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.