Run a Web node on Linux

Use a Linux Web node when the browser ingress runs on a Linux host, for example a cloud VM in front of a private control plane.

The control plane still runs on a Mac. The Linux host runs only oore-web, which serves the web UI and proxies API requests to oored.

oore install does not manage Linux hosts. You install the archive and the systemd unit once. After that, oore-web update and the web UI update the Web node in place.

What you need

• A Linux host on x86_64 or arm64 with systemd.
• ssh-keygen from OpenSSH. oore-web update uses it to verify signed release metadata.
• A protected network path from the host to the control plane, such as a private overlay network.
• A ready control plane that uses Identity provider or Trusted Proxy access.
• For Trusted Proxy access, the backend proof file and the upstream proof file described in Trusted Proxy.

1. Install the archive

Create a service account and an install root that it owns:

sudo useradd --system --home-dir /opt/oore-web --shell /usr/sbin/nologin oore-web
sudo install -d -o oore-web -g oore-web -m 0750 /opt/oore-web

Download oore-web_<version>_linux_x86_64.tar.gz (or _linux_arm64) and oore_<version>_checksums.txt from the release. Verify the archive, then extract it as the service account:

sha256sum --ignore-missing -c oore_<version>_checksums.txt
sudo -u oore-web tar -xzf oore-web_<version>_linux_x86_64.tar.gz -C /opt/oore-web

The service account must own the install root. The web UI update replaces bin/oore-web and web-dist as that account.

Store each proof in a file that only the service account can read:

sudo install -d -o root -g oore-web -m 0750 /etc/oore-web
sudo install -o oore-web -g oore-web -m 0400 backend-proof /etc/oore-web/backend-proof
sudo install -o oore-web -g oore-web -m 0400 upstream-proof /etc/oore-web/upstream-proof

2. Install the systemd unit

Save this unit as /etc/systemd/system/oore-web.service. Replace the backend URL with the control plane’s address on the protected network:

[Unit]
Description=Oore web node
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=oore-web
Group=oore-web
Environment=OORE_INSTALL_ROOT=/opt/oore-web
ExecStart=/opt/oore-web/bin/oore-web serve \
  --listen 127.0.0.1:4173 \
  --backend-url http://100.64.10.20:8787 \
  --backend-transport-protected \
  --trusted-proxy-secret-file /etc/oore-web/backend-proof \
  --upstream-trusted-proxy-secret-file /etc/oore-web/upstream-proof
Restart=on-failure
RestartSec=2
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

Omit both proof options for Identity provider access.

The unit must be named oore-web.service, must run oore-web directly, and must use Restart=on-failure or Restart=always. After an update, oore-web exits with status 75 and relies on systemd to start the new release.

Start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now oore-web

Keep the listener on loopback. Terminate TLS and authenticate users at the ingress proxy on the same host, then forward to 127.0.0.1:4173.

A user unit in ~/.config/systemd/user also works when lingering is on for that account (loginctl enable-linger <user>). Without lingering, the unit stops when the account logs out, so Oore does not offer updates from the web UI.

3. Verify the Web node

Check the frontend and the control plane through it:

/opt/oore-web/bin/oore-web status --url http://127.0.0.1:4173

A healthy Web node prints Frontend: ok and Backend: ok, each with its version and channel, and a Ready: line with database=true migrations=true encryption=true. The command exits with status 1 when either check fails.

Then confirm the service and the browser path:

1. Run systemctl status oore-web. The unit is active (running).
2. Open the public HTTPS URL in a browser and sign in.
3. As the instance owner, open Settings > General. Under Runtime, the Frontend row shows the Web node’s version and channel.

Update the Web node

From the web UI, select Update frontend. oore-web downloads and verifies the release, replaces its files, and exits so systemd restarts it.

From a shell, run the update as the service account, then restart the unit:

sudo -u oore-web OORE_INSTALL_ROOT=/opt/oore-web /opt/oore-web/bin/oore-web update
sudo systemctl restart oore-web

oore-web update warns when it cannot find a suitable oore-web.service unit.

Change the release channel

oore-web update stays on the channel the Web node was installed from. To move the Web node to another channel, for example to follow a control plane that moved from stable to alpha, name the channel and confirm the switch:

sudo -u oore-web OORE_INSTALL_ROOT=/opt/oore-web /opt/oore-web/bin/oore-web update --channel alpha --switch-channel
sudo systemctl restart oore-web

oore-web records the new release and channel, so later updates follow it. Update Oore in the web UI also moves the frontend to the backend’s channel.

A switch never downgrades. If the target channel’s latest release is older than the installed version, the update stops without changes.

Run oore-web status from step 3 and confirm that the frontend reports the new version and channel.

Troubleshooting

oore-web status reports Frontend: failed

oore-web is not running, or --url points somewhere else. Check systemctl status oore-web and journalctl -u oore-web, and keep the URL on the --listen address from the unit.

oore-web status reports a backend liveness or readiness failure

The Web node cannot reach oored, or oored is not ready. Check the --backend-url address in the unit, the protected network path to the control plane, and oore status on the control plane. A Ready: line with a false value names the failing check.

The status says the response did not pass through oore-web

--url points at the control plane or the ingress proxy instead of oore-web. Use the loopback address from --listen.

Update frontend stays disabled

The Frontend row under Runtime shows the reason. Common reasons are a unit with another name, a unit without a restart policy, a user unit without lingering, and an oore-web process started from a shell instead of by systemd.

An update fails

If the update fails, Oore keeps the previous release and shows the failure after the next restart. The full output is in /opt/oore-web/logs/oore-web-update.log.

Oore says only the instance owner can manage updates

If Oore says that only the instance owner can manage updates, read the reason it gives. Behind a Trusted Proxy, oore-web forwards the identity header only when the upstream proxy also sends the upstream proof. Without --upstream-trusted-proxy-secret-file, it strips the header and the control plane does not recognize the session.

The Web node runs in a container or under pm2

Containers and process managers such as pm2 are not supported for updates from the web UI. Replace the container image or archive instead.

Next step

Monitor Oore and include the Web node in your upgrade plan.