Install on Linux

Nexus ships as a .deb for Debian and Ubuntu and an .rpm for Fedora and RHEL (Rocky and Alma too), both for x86-64 — Ubuntu 24.04 or later, Debian 13 or later, Fedora 39 or later, RHEL/Rocky/Alma 10 or later. Building from source is still supported and is the only route on other distributions.

Studio and Lens are Windows-only

A Linux install is headless. Engineers connect to it from a Windows workstation running Studio.

Install from the package

On Debian or Ubuntu:

sudo apt install ./raylux-nexus_<version>_amd64.deb

On Fedora, RHEL, Rocky or Alma:

sudo dnf install ./raylux-nexus-<version>-1.x86_64.rpm

Either is the whole install. It creates the raylux service account, installs the systemd unit, and enables and starts Nexus. It is non-interactive, so it works over SSH and from a provisioning script.

Then continue to First run to create your administrator account.

Where things go

Nexus installs under /opt/raylux, not /usr. It carries its own free-threaded CPython runtime — no distribution packages that interpreter — and /opt is where a self-contained vendor package belongs.

Path	Contents
/opt/raylux/bin/raylux-nexus	Nexus
/opt/raylux/bin/python/	the bundled Python runtime
/opt/raylux/lib/	bundled libraries
/opt/raylux/share/raylux/web/	the operator runtime
/opt/raylux/share/raylux/fonts/	fonts embedded into report PDFs
/lib/systemd/system/raylux-nexus.service	the service unit
/var/lib/raylux/	your data — see below
/var/log/raylux/	rotating log file

Everything Nexus owns lives in /var/lib/raylux: the project file, the historian, the audit log, the secrets store and the TLS key material.

Check it

systemctl status raylux-nexus              # active (running)
curl http://localhost:8080/health          # {"status":"ok"}
curl http://localhost:8080/health/ready    # {"status":"ready"}

/health answers as soon as the process is up; /health/ready only once Nexus can actually serve. Gate scripts and load balancers on ready.

Which package do I need?

amd64 (.deb) or x86_64 (.rpm) for an ordinary 64-bit server — those are what each release publishes. arm64 for a Raspberry Pi or other 64-bit ARM board is not in the published release downloads; ask for a build. The architecture is in the filename. Installing the wrong one fails immediately and harmlessly — the package manager will tell you. The arm64 package has been installed and run on a Raspberry Pi Compute Module 3 running Raspberry Pi OS (64-bit); a CM3 with 1 GB RAM runs the gateway at ~35 MB RSS idle.

Build from source

Use this on a distribution with no package, or when you want to change something. The result is a working install on the machine that built it, not a relocatable one: the binary finds its Python runtime through a path baked in at build time.

Prerequisites

• A 64-bit Linux with GCC 13 or later.
• CMake 3.25+, Ninja, and vcpkg.
• A free-threaded CPython 3.14t build.
• Node.js, to build the web bundle.

1. Build

Nexus builds without the Studio toolchain, so a server does not need Qt:

export RAYLUX_PYTHON_HOME=/opt/python3.14t
export VCPKG_ROOT=/opt/vcpkg

cmake -B build -S . \
  -DRAYLUX_NEXUS_ONLY=ON \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
cmake --build build --parallel

Build the operator runtime too, unless you want a Nexus instance with no screens:

npm ci --prefix web
npm run build --prefix web

The install step looks for the web bundle when it runs, so the order of these two builds does not matter.

2. Install

sudo cmake --install build --prefix /usr/local
sudo systemd-sysusers            # creates the `raylux` account
sudo systemctl daemon-reload
sudo systemctl enable --now raylux-nexus

A source install puts Nexus in /usr/local/bin and its files under /usr/local/share/raylux; the data directory is /var/lib/raylux either way.

If the web bundle is missing the install warns and continues — a headless Nexus is a legitimate deployment.

Building the package yourself

scripts/build-deb.sh

Needs the prerequisites above plus patchelf. patchelf is not optional: it rewrites the binary's library path so the package works wherever it is installed. Without it the build stops rather than produce a package that installs cleanly and then cannot start.

Opening the firewall

Nothing opens ports for you.

sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --permanent --add-port=8443/tcp
sudo firewall-cmd --reload

Or, on a ufw system:

sudo ufw allow 8080/tcp
sudo ufw allow 8443/tcp

Operating it

journalctl -u raylux-nexus -f      # live log
sudo systemctl restart raylux-nexus
sudo systemctl stop raylux-nexus

Nexus also writes its own rotating log to /var/log/raylux/raylux_nexus.log.

To raise the log level temporarily without editing the packaged unit:

sudo systemctl edit raylux-nexus

[Service]
ExecStart=
ExecStart=/opt/raylux/bin/raylux-nexus --log-level debug

Then sudo systemctl restart raylux-nexus. Remove the override the same way when you are done — debug logging writes a line per system tag per second, which is a lot of journal on a long-running gateway and real wear on an SD card.

Known limitations

• A source install is not relocatable. The binary locates libpython3.14t.so through a build-time path, so copying it to another machine will not work. The .deb does not have this problem.
• No configuration migration. Upgrading across a change in the configuration format is currently a manual edit.
• No container image on x86_64. Both .deb and .rpm are built and checked in CI; the Edge arm64 image in deploy/edge/ is the only container image.
• If you move Nexus to port 443, add AmbientCapabilities=CAP_NET_BIND_SERVICE and the matching CapabilityBoundingSet to the unit. Do not run it as root.