Install on Linux

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

The Linux sink runs as a systemd service and starts automatically on boot. 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)
Python 3.9 or later
pip and venv available
Network connectivity to the Hub host and port (outbound TCP — no inbound rules needed)
sudo privileges

Installation

Step 1 — Download and extract

Obtain the sink package from your administrator or from your organisation’s release server. Extract it to the installation directory:

sudo mkdir -p /opt/nexomatic-sink
sudo tar -xzf nexomatic-sink-linux.tar.gz -C /opt/nexomatic-sink

Step 2 — Create a virtual environment and install dependencies

cd /opt/nexomatic-sink
sudo python3 -m venv venv
sudo venv/bin/pip install -r requirements.txt

Step 3 — Create a dedicated service user

Running the service as a dedicated user follows least-privilege best practice:

sudo useradd --system --no-create-home --shell /bin/false nexomatic
sudo chown -R nexomatic:nexomatic /opt/nexomatic-sink

Step 4 — Create the systemd unit file

Create /etc/systemd/system/nexomatic-sink.service with the following content. Replace the placeholder values with those provided by your administrator.

[Unit]
Description=Nexomatic Linux Sink Service
After=network.target

[Service]
Type=simple
User=nexomatic
WorkingDirectory=/opt/nexomatic-sink
ExecStart=/opt/nexomatic-sink/venv/bin/python3 /opt/nexomatic-sink/sink_service.py
Restart=always
RestartSec=5s

# Connection configuration
Environment=HUB_HOST=hub.example.com
Environment=HUB_PORT=50051
Environment=CLIENT_ID=LINUX:BASE
Environment=CLIENT_SECRET=<your-client-secret>

# Tenant pinning (optional — omit to serve all tenants)
Environment=TENANT_UUID=<your-tenant-uuid>
Environment=TENANT_SECRET=<your-tenant-secret>

# Allow the service to write to its own directory (for updates and logs)
ReadWritePaths=/opt/nexomatic-sink

[Install]
WantedBy=multi-user.target

Step 5 — Enable and start the service

sudo systemctl daemon-reload
sudo systemctl enable nexomatic-sink
sudo systemctl start nexomatic-sink

Step 6 — 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.

Environment Variables Reference

Variable	Required	Description
`HUB_HOST`	Yes	Hub hostname or IP
`HUB_PORT`	Yes	Hub port (default `50051`)
`CLIENT_ID`	Yes	Sink Type name (e.g. `LINUX:BASE`)
`CLIENT_SECRET`	Yes	Client secret for this Sink Type
`TENANT_UUID`	No	Pin the sink to a single tenant
`TENANT_SECRET`	No	Tenant registration secret
`LOG_FOLDER`	No	Override the directory for log files

Automatic Updates

When your administrator publishes a new version, the Hub signals the service to update. The service will:

Finish any in-progress tasks
Download the new package and extract it over the existing installation
Run pip install -r requirements.txt if dependencies changed
Call sys.exit(0) — systemd’s Restart=always restarts it 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

Troubleshooting

Symptom	Likely cause	Fix
Service fails to start	Python not found or path wrong	Verify `which python3` and update `ExecStart`
`OFFLINE` in UI	Cannot reach Hub	Test connectivity: `nc -zv hub.example.com 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 in Nexomatic