Installation

QUBIQ ships as one installer per operating system. It places the application, registers it with the operating system's service manager so it starts on boot, opens the firewall for the web interface and the REST gateway (Windows), and takes you to the first-run setup screen.

There is nothing to install alongside it. No database server, no message broker, no web server — and no Python. The Python runtime that powers scripting is bundled inside QUBIQ's own folder. The one external store a production plant needs for history is QuestDB 9.4.0 or later — see system requirements.

Before you start

• Check system requirements.
• Have administrator rights. QUBIQ installs as a machine-wide service on every platform, which is the only mode that makes sense for a plant: a login-start install would stop the moment the operator logged out, taking the historian and every device connection with it.
• QUBIQ is 64-bit only. The Windows installer refuses a 32-bit host rather than installing cleanly and failing to start, which is far harder to diagnose.

Code signing

If your download is not code-signed, Windows SmartScreen and macOS Gatekeeper show a one-time "unrecognised publisher" prompt — choose More info → Run anyway (Windows) or right-click → Open (macOS). Nothing else is affected. Either way, check the download against the published SHA256SUMS.

QUBIQ Setup New in 1.0.8

QUBIQ Setup is the same installer window on Windows, macOS and Linux:

OS	Download	Run
Windows	QUBIQ-<version>-setup.exe	Double-click and approve the administrator prompt.
macOS	QUBIQ-<version>-arm64.dmg (or -x64)	Open it and double-click Install QUBIQ.
Linux (desktop, x64)	qubiq-setup-<version>-linux-x64.tar.gz	Extract it and run ./qubiq-setup.

1. Read the License Agreement — the link beside the checkbox opens the full text — and tick I have read and agree to the License Agreement. Install now stays disabled until you do.
2. Optionally open Custom options: the install location (Windows only — the macOS and Linux packages always install to a fixed folder), and Start QUBIQ when installation finishes (macOS and Linux, on by default; Windows always starts the service).
3. Click Install now. Progress and a live log are shown. A failure shows the error, the path of the log file and Copy log.
4. Click Open QUBIQ to create the first administrator in your browser.

Under the window, Setup drives each platform's native package — the Windows installer engine, the macOS .pkg, the .deb/.rpm through the system package manager — which still does the installing. Every route into QUBIQ requires accepting the License Agreement, including the unattended ones below.

Windows ships one file

Changed in 1.0.8 Earlier releases shipped a classic step-by-step Windows installer. The only Windows download is now QUBIQ-<version>-setup.exe, which is QUBIQ Setup. The installer engine inside it refuses to run unless Setup launched it, so there is no second way in that skips the License Agreement.

Updating over an existing installation New in 1.0.8

Setup detects an installed QUBIQ — its version, and whether it is running — and says what it is about to do before you click:

Found	Setup shows	Button
An older version	Update QUBIQ 1.0.7 → 1.0.8	Update now
The same version	QUBIQ 1.0.8 is already installed	Reinstall
A newer version	The install is blocked, with the reason	—
Either of the first two, running	An amber notice: Setup will stop QUBIQ, connected devices and screens are offline for a minute or two, and it is started again when it is done	Stop QUBIQ and update / Stop QUBIQ and reinstall

An update always installs in place: the install location is locked to the existing folder, so an update can never create a second QUBIQ. Projects, data and the licence are kept. The previous version's program folders are removed before the new ones are copied, so files a release stopped shipping do not accumulate; the data directory is never touched.

Windows

Run QUBIQ-<version>-setup.exe and follow QUBIQ Setup. The default folder is C:\Program Files\QUBIQ.

It registers the Windows service with the Service Control Manager, sets it to Automatic start with a restart-on-failure policy, starts it, opens the firewall for ports 8182 and 8090, and grants the data directory only to SYSTEM and the local Administrators group.

Programs and Features shows the real size. 1.0.8 Earlier installers measured the folder after the service had started, and counted each per-service link to the one QUBIQ binary as a full copy — a 0.4 GB install was listed at about 5.6 GB. The size is now measured before the service starts.

The service survives a slow boot. 1.0.8 Windows gives a service about 30 seconds to report in. QUBIQ now reports to the Service Control Manager first and keeps reporting progress while it boots, so a long start — restoring a large store-and-forward backlog after an unclean stop, for example — no longer fails the service start at exactly the moment the plant needs it back.

Unattended, with the same file:

start /wait QUBIQ-<version>-setup.exe /S /ACCEPTEULA /D=C:\path\to\QUBIQ

/ACCEPTEULA is required with /S and records that you have read and accept EULA.txt; without it a silent install refuses to run. /D= is optional, must come last and is not quoted. Exit codes: 0 installed, 2 failed, 3 /ACCEPTEULA missing, 4 unknown argument. The log is written to %TEMP%\qubiq-setup-silent-<time>.log.

qubiq.exe is hidden, and refuses to run on its own

Running the engine by hand boots the whole platform outside the service — a plant that dies with your session and never returns after a reboot, with nothing about the double-click to suggest it. So the installer hides the executable, and the binary itself refuses to start unless it was installed. Use the service, or qubiqctl.

Linux

On a desktop, use QUBIQ Setup. On a server without a desktop, use the script in the Linux tarball. It shows the License Agreement, asks you to type accept, then installs the package with apt, dnf or zypper:

sudo ./install.sh                    # interactive
sudo ./install.sh --accept-eula      # unattended, after reading EULA.txt

Or install the package directly:

sudo apt install ./qubiq_<version>_amd64.deb      # Debian, Ubuntu
sudo dnf install ./qubiq-<version>.x86_64.rpm     # RHEL, Rocky, Fedora

The package unpacks the bundled Python runtime, creates a dedicated qubiq system account that owns the data directory, installs a systemd unit and enables it without starting it — an unattended package install must not bring a plant up at a moment nobody chose. An upgrade of a QUBIQ that was running starts it again; on a first install, start it yourself:

sudo systemctl start qubiq
systemctl status qubiq

Then open http://<host>:8182.

macOS

Open the disk image and double-click Install QUBIQ (QUBIQ Setup), or run QUBIQ-<version>-<arch>.pkg directly, which shows the License Agreement in Installer.app.

The package installs to /usr/local/qubiq and registers a LaunchDaemon, com.qubiq. Like the Linux package it does not start QUBIQ on a first install — Setup does, unless you cleared Start QUBIQ when installation finishes. An upgrade of a QUBIQ that was running starts it again. From a terminal:

sudo installer -pkg QUBIQ-<version>-arm64.pkg -target /
sudo launchctl load /Library/LaunchDaemons/com.qubiq.plist

Then open http://localhost:8182.

---

Where things are installed

	Windows (all users)	Linux	macOS
Application	C:\Program Files\QUBIQ	/opt/qubiq	/usr/local/qubiq
Data directory	C:\ProgramData\QUBIQ	/var/lib/qubiq	/Library/Application Support/QUBIQ
Bundled Python	…\QUBIQ\python	/opt/qubiq/python	/usr/local/qubiq/python
Its bundled packages	…\QUBIQ\python-packages-bundled	/opt/qubiq/python-packages-bundled	/usr/local/qubiq/python-packages-bundled
Service unit	Windows service QUBIQ	/lib/systemd/system/qubiq.service	/Library/LaunchDaemons/com.qubiq.plist
Open-source notices	…\QUBIQ\THIRD-PARTY-NOTICES.md	/usr/share/doc/qubiq/	/usr/local/qubiq/THIRD-PARTY-NOTICES.md
License Agreement	EULA.txt, in the download	/usr/share/doc/qubiq/EULA.txt	EULA.txt, in the download

The installer pins the data directory with the QUBIQ_DATA_DIR environment variable, so a service account with no user profile still finds it.

Inside the data directory:

.env                JWT_SECRET and ENCRYPTION_KEY — generated on first boot
projects/           per-project view, script and asset trees
user-databases/     sandbox for user-created SQLite connections
python-packages/    admin-installed Python modules for the script sandbox
mibs/               uploaded SNMP vendor MIBs
log/                rotated diagnostic reports
nats_data/          the message bus's durable store: store-and-forward buffers and the quarantine
backups/            background backup jobs and their finished archives (kept 7 days, newest 10)

nats_data/ holds plant data — history and writes not yet delivered, and writes waiting for an operator in quarantine. 1.0.8 Until 1.0.8 it sat beside the binary in the install folder, where a reinstall into another folder or a cleaned install folder lost it. The first boot of 1.0.8 moves it into the data directory; if both copies exist, the one in the install folder wins and the other is set aside as nats_data.stale-<time>, never deleted.

The directory also holds the configuration database, encrypted at rest.

The directory is created with restrictive permissions — a locked ACL on Windows, owner-only on Unix — because it holds the configuration database, .env and every connection credential.

Back up .env separately

It holds ENCRYPTION_KEY. Lose it and the configuration database and every stored credential are unrecoverable — a backup of the data directory alone will not save you. → Backup & restore

---

Python is bundled — do not install your own

QUBIQ ships a private, version-pinned Python runtime inside its install folder, with the two things the platform needs already in it:

Bundled	For
Python runtime	Pipeline Python nodes and Gateway scripts
Transport library	How the worker reaches the platform
ruff	The in-editor Python linter

The installer points PYTHON_PATH at it. That runtime is not added to your system PATH, does not register as "the system Python", cannot collide with a Python you already have, and is removed when you uninstall.

So: scripting works out of the box. You do not need to install Python, create a virtual environment, or run pip install to get started.

To add extra modules for your scripts — pandas, a vendor SDK — use Settings → Script Sandbox → Add & install in the interface. Packages land in python-packages/ inside the data directory, which keeps them separate from the bundled runtime and means they survive a QUBIQ upgrade. → The script sandbox

If scripting is unavailable

QUBIQ boots degraded rather than failing: the interface works, connections poll, screens render — only Python script nodes and Gateway scripts fail. If that happens after an install, the bundled runtime did not land; reinstall rather than pointing PYTHON_PATH at a system Python.

---

Ports and the firewall

On Windows the installer adds firewall rules for two ports.

Port	Service	Opened by the installer	Notes
8182	Web interface and API	Yes	The port engineers and operators connect to.
8090	REST gateway — API-key data ingress/egress	Yes	The intended door for third-party systems. Remove the rule if nothing outside the host uses it.
8183	Telemetry WebSocket	No	The browser reaches it from the same origin as 8182, so it needs no rule of its own.
8091	Script gateway	No	Loopback only. Never exposed.

The internal message bus is not in this table and never will be: it binds to loopback on a random port, so there is nothing to open, firewall or authenticate. → The gateway

TLS on 8090

Port 8090 carries API keys over the network. Enable TLS, or put the gateway behind a TLS-terminating reverse proxy, before you issue keys to anything. → API keys

---

After installing

1. Open http://localhost:8182 and complete the first-run setup — QUBIQ ships with no default account, and the wizard is reachable only until you create the first one.
2. Point the historian at a QuestDB store — QuestDB 9.4.0 or later → Historian configuration.
3. Point the audit journal at an external database → Audit journal.
4. Take a baseline backup → Backup & restore.

---

Managing the service

Day to day, use your platform's service manager, or the bundled qubiqctl control utility, which detects the installed service manager and delegates to it so shutdown is always graceful.

Linux / macOS

qubiqctl start | stop | restart | status

Windows (elevated)

qubiqctl.bat start | stop | restart | status

→ Services & system settings

Serving over HTTPS

Terminate TLS at QUBIQ or at a reverse proxy.

At QUBIQ — set in .env inside the data directory:

TLS_ENABLED=true
TLS_CERT_FILE=/etc/qubiq/tls/fullchain.pem
TLS_KEY_FILE=/etc/qubiq/tls/privkey.pem

Behind a proxy — proxy 8182 (HTTP + WebSocket upgrade) and 8183, and declare the proxy so client addresses are attributed correctly in the audit journal:

TRUSTED_PROXIES=10.0.0.0/8,192.168.0.0/16
ALLOWED_ORIGINS=https://qubiq.example.com
QUBIQ_COOKIE_SECURE=true

→ Environment variables

Upgrading

Run the new installer over the existing installation — it shows Update QUBIQ with both versions, and warns first if QUBIQ is running. → Updating over an existing installation

It stops the service, removes the previous version's program folders, installs the new ones into the same folder and starts QUBIQ again. It never touches the data directory or .env.

The database schema is migrated once at boot, before any service starts, so there is no separate migration step.

Take a backup first — schema migrations are not reversible.

Upgrading to 1.0.8: QuestDB 9.4.0 or later

The historian now requires QuestDB 9.4.0 or later. A historian store that is already designated keeps recording on an older QuestDB, but raises a critical alert until QuestDB is upgraded; a new designation of an older store is refused. Upgrade QuestDB before or after QUBIQ — nothing is lost either way. → Historian configuration

Uninstalling Changed in 1.0.8

QUBIQ Uninstall is the same window as QUBIQ Setup:

OS	Open it
Windows	Settings → Apps → QUBIQ → Uninstall (or Programs and Features), or Start → QUBIQ → Uninstall QUBIQ
macOS	Uninstall QUBIQ.app, on the QUBIQ disk image
Linux (desktop)	./qubiq-setup --uninstall, from the Linux tarball

It stops QUBIQ, deregisters the service, removes the firewall rules and the program files. Your data is kept unless you tick Also delete all QUBIQ data. Ticking it lists exactly what goes — projects and views, the database, users and roles, the licence, backups, logs, and the encryption key — shows the folder, and turns the button into a red Uninstall and delete data. Kept data is picked up again by a reinstall.

Without the window:

Windows   QUBIQ-Uninstall.exe /S [/DELETEDATA]      (in the install folder)
macOS     sudo /usr/local/qubiq/uninstall.sh [--delete-data]
Linux     sudo apt remove qubiq  |  sudo dnf remove qubiq
          then, only to delete the data: sudo rm -rf /var/lib/qubiq

Export a backup before deleting the data if there is any chance you will want the configuration back.

Next

→ First-run setup