Install on Linux

import { Aside } from ‘@astrojs/starlight/components’;

The Linux sink runs as a systemd service and starts automatically on boot. It uses a single pre-built binary — no Python runtime or virtual environment needed. It supports self-updating: new versions are applied automatically when signalled by the Hub.

---

Prerequisites

• Linux with systemd (Ubuntu 20.04+, Debian 11+, RHEL 8+, or equivalent)
• curl installed — the installer auto-installs it on Debian/Ubuntu; other distros must install curl manually
• Network connectivity to the Hub host and port (outbound TCP — no inbound rules needed)
• Network connectivity to the controller URL (for downloading the binary and updates)
• sudo privileges
• A configured Sink Type with its Client ID and Client Secret (see Sink Types & Configuration)

---

Quick Install

The installer script handles everything: creating the service user, downloading the binary, writing the systemd unit, and starting the service.

curl -fsSL https://<controller-url>/api/install-linux-service.sh | \
  sudo bash -s -- --controller-url https://<controller-url> --client-secret <your-client-secret>

Replace <controller-url> with your Nexomatic controller hostname and <your-client-secret> with the secret from your Sink Type.

---

Step-by-Step Installation

Step 1 — Obtain the installer

Download the installer script from your controller or from your organisation’s release server:

curl -O https://<controller-url>/api/install-linux-service.sh
chmod +x install-linux-service.sh

Alternatively, your administrator may provide a zip bundle containing the binary and installer together.

Step 2 — Run the installer

At minimum you need --controller-url and --client-secret. All other flags have sensible defaults.

sudo ./install-linux-service.sh \
  --controller-url https://controller.example.com \
  --client-secret <your-client-secret>

The installer will:

1. Check dependencies (curl, systemd)
2. Create the nexomatic system user and group
3. Create /opt/nexomatic-sink/ with data and logs directories
4. Download the nexomatic-sink binary from the controller’s downloads API
5. Create the systemd unit file at /etc/systemd/system/nexomatic-sink.service
6. Set permissions and enable the service
7. Optionally start the service immediately

Step 3 — Confirm in the UI

Check the service is running:

systemctl status nexomatic-sink

Within a few seconds the sink should appear as ONLINE on the Sinks screen in Nexomatic.

---

Installer Options Reference

Flag	Default	Description
--controller-url	(required)	Controller URL; used to fetch the binary and for the running service
--server-url	Same as --controller-url	Override the controller URL used by the running service
--client-secret	(required)	Client secret from your Sink Type
--client-id	REMOTE:LINUX	Client ID — must match the Sink Type name
--hub-host	localhost	Hub gRPC hostname
--hub-port	50051	Hub gRPC port
--hub-tls	true	Use TLS for the gRPC connection (default for external LoadBalancers)
--no-hub-tls	—	Disable TLS (only for local/plaintext debugging)
--auth-method	client_credentials	Authentication method: client_credentials, entra_id, google, github, or none
--max-processes	4	Maximum concurrent task processes
--tenant-uuid	(none)	Pin the sink to a single tenant (omit for multi-tenant)
--tenant-secret	(none)	Node registration secret (required if tenant enforces node auth)
--update-base-url	(none)	Base URL for self-update packages (e.g. https://releases.example.com/nexomatic-sink)
--node-version	(auto-detected)	Version string written to the VERSION file
--node-type-uuid	(seeded UUID)	NodeType UUID

---

Environment Variables Reference

These are written to the systemd unit file by the installer. If you need to change them later, edit /etc/systemd/system/nexomatic-sink.service and run sudo systemctl daemon-reload && sudo systemctl restart nexomatic-sink.

Variable	Required	Description
SERVER_URL	Yes	Controller API URL
HUB_HOST	Yes	Hub gRPC hostname or IP
HUB_PORT	Yes	Hub gRPC port (default 50051)
HUB_TLS	Yes	true to use TLS, empty for plaintext
CLIENT_ID	Yes	Sink Type identifier (e.g. REMOTE:LINUX)
CLIENT_SECRET	Yes	Client secret for the Sink Type
CLIENT_TYPE	Yes	Same as CLIENT_ID
AUTH_METHOD	Yes	client_credentials, entra_id, google, github, or none
MAX_PROCESSES	No	Maximum concurrent tasks (default 4)
LOOP_INTERVAL	No	Polling interval in seconds (default 10)
LOG_RETENTION_DAYS	No	Days to retain local logs (default 7)
ROOT_FOLDER	Yes	Installation root (/opt/nexomatic-sink)
TENANT_UUID	No	Pin the sink to a single tenant
TENANT_SECRET	No	Tenant registration secret
NODE_TYPE_UUID	Yes	NodeType UUID for identity
NODE_VERSION	No	Installed version string
UPDATE_BASE_URL	No	Base URL for self-update downloads

---

How the Binary Is Obtained

The installer downloads the sink binary from the controller’s Downloads API:

1. The installer calls GET /api/v1/downloads/latest/linux/nexomatic-sink-linux-x86_64/url
2. The controller returns a presigned URL (time-limited download link)
3. The installer downloads the binary from the presigned URL
4. The binary is placed at /opt/nexomatic-sink/nexomatic-sink and made executable

If you have a bundled zip (binary + installer), the installer uses the local binary instead of downloading.

---

Automatic Updates

When --update-base-url is configured, the sink checks for newer versions at startup and when signalled by the Hub. The update process:

1. Finish any in-progress tasks
2. Download the new package zip from the update base URL
3. Extract it over the existing installation
4. Call sys.exit(0) — systemd’s Restart=always restarts the service with the new code

No manual action is required. The service will be briefly offline during the update.

---

Managing the Service

# View status and recent logs
systemctl status nexomatic-sink

# Follow live logs
journalctl -u nexomatic-sink -f

# Stop / start / restart
sudo systemctl stop nexomatic-sink
sudo systemctl start nexomatic-sink
sudo systemctl restart nexomatic-sink

---

Uninstalling

sudo systemctl stop nexomatic-sink
sudo systemctl disable nexomatic-sink
sudo rm /etc/systemd/system/nexomatic-sink.service
sudo systemctl daemon-reload
sudo rm -rf /opt/nexomatic-sink
sudo userdel nexomatic

To keep logs and data files, back up /opt/nexomatic-sink/nexomatic_data/ before removing.

---

Troubleshooting

Symptom	Likely cause	Fix
Service fails to start	Binary not executable or missing	Check /opt/nexomatic-sink/nexomatic-sink exists and has execute permissions
OFFLINE in UI	Cannot reach Hub	Test connectivity: nc -zv <hub-host> 50051
Immediately restarts	Bad credentials	Check journalctl -u nexomatic-sink -n 50 for auth errors
Tasks not appearing	Sink Type mismatch	Confirm CLIENT_ID matches the Sink Type name in Nexomatic
TLS errors	Wrong TLS setting	If connecting to a plaintext port, use --no-hub-tls

All service output (stdout and stderr) is captured by journald. Use `journalctl -u nexomatic-sink` to view the full log history.