Skip to main content

Running headless

The engine has no user interface and needs no Qt. Configure your hubs and rules in the desktop app, then hand the resulting data/ folder to a server.

Set the target OS before you type paths​

This is the step that catches people out. Watch paths have to be valid on the machine that runs the engine, not the one that configured it. Configure on Windows and deploy on Linux, and D:\Releases\Movies means nothing on the server.

In the desktop app, open Settings and set Target runtime OS to Linux first, then enter each rule's watch path as it will be on the server or inside the container.

Then check it where it will run:

python herald_cli.py --check

That validates the configuration and reports every watch path that does not resolve. --list prints the configured hubs and which of them are enabled. Running without arguments starts every enabled hub, and Ctrl-C stops it.

Docker​

The image is ghcr.io/luadch-ng/herald:latest. It needs two mounts: the configuration you created in the desktop app, and the release trees to watch. Read-only is enough for the latter.

docker run -d --name herald \
  -v /path/to/herald-data:/app/data \
  -v /path/to/releases:/releases:ro \
  ghcr.io/luadch-ng/herald:latest

The container runs as uid 1000, so the mounted data directory has to be writable by it:

mkdir -p herald-data && sudo chown -R 1000:1000 herald-data

Watch paths in the rules must match the mount points inside the container, so a rule watching /releases/Movies needs the host directory mounted at /releases. The repository ships a docker-compose.yml with both mounts laid out.

systemd​

For a plain install without Docker, Herald ships an example unit at deploy/herald.service. Put Herald in /opt/herald, including the data/ folder from the desktop app, and give it a virtual environment with the core dependencies only:

python3 -m venv /opt/herald/.venv
/opt/herald/.venv/bin/pip install -r /opt/herald/requirements-core.txt
/opt/herald/.venv/bin/python /opt/herald/herald_cli.py --check

Then install and start it:

sudo cp /opt/herald/deploy/herald.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now herald
journalctl -u herald -f

The unit sends SIGTERM on stop, which Herald handles as a clean shutdown and disconnects from every hub rather than dropping the connections.