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.

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. Create the omnibus system user and add it to the dialout (serial) and input groups.
5. Deploy to /opt/omnibus and install production dependencies there.
6. Create the persistent data directory /var/lib/omnibus (mode 0750).
7. Install and start the hardened omnibus systemd unit.
8. 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 the 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.