Background service

Webhook Relay agent can run in the background and be managed by the operating system on Linux, Windows and MacOS. To start using the background service, first get the CLI following installation instructions.

Configuration file

When running as a background service, agent needs a configuration file. It’s a simple yaml format file.

For this file, you will need to:

Now, populate the file:

version: "v1"
key: your-secret-key # will be encrypted on startup
secret: your-secret # will be encrypted on startup
tunnels:
- tunnel-1-name
- tunnel-2-name
buckets:
- bucket-1-name
- bucket-2-name

If no tunnels or no buckets are defined, that part of the relay service will be disabled. If no buckets and tunnels are specified, relay service will not start.

Note that you can subscribe to tunnels and buckets even before you have created them through the API/CLI/UI.

Once the relay service starts, key and secret will be encrypted.

Linux

Tu install the service, you will need to use sudo and provide a full path to relay configuration file:

sudo relay service install -c /full/path/config.yaml
sudo relay service start

To specify credentials during install:

sudo relay service install -c /full/path/config.yaml --key [YOUR KEY] --secret [YOUR SECRET]

Restart

To restart the service (if you change the configuration file

sudo relay service restart

Uninstall

To uninstall the service:

sudo relay service stop
sudo relay service uninstall

To view service logs, use journalctl:

journalctl -u relay.service -f

Windows

Make sure you have download relay CLI and created a config.yaml file.

If you are using Powershell:

.\relay-windows-amd64.exe service install -c .\config.yaml
.\relay-windows-amd64.exe service start

You can also just keep the config.yaml file in the same directory as relay exe file. Then, you just need to do:

.\relay-windows-amd64.exe service install
.\relay-windows-amd64.exe service start

The agent is now installed and will be run after a system reboot.

To specify credentials during install:

.\relay-windows-amd64.exe service installl -c .\full\path\config.yaml --key [YOUR KEY] --secret [YOUR SECRET]

Restart

To restart the service (if you change the configuration file):

.\relay-windows-amd64.exe service restart

Uninstall

To uninstall the service:

.\relay-windows-amd64.exe service stop
.\relay-windows-amd64.exe service uninstall

MacOS

Execute as the user who will run the agent:

relay service install -c /full/path/config.yaml -u your-user
relay service start

To specify credentials during install:

relay service install -c /full/path/config.yaml --key [YOUR KEY] --secret [YOUR SECRET]

Restart

To restart the service (if you change the configuration file):

relay service restart

Uninstall

To uninstall the service:

relay service stop
relay service uninstall

Note: The service needs to be installed from the Terminal by running its GUI interface as your current user. Only then will you be able to manage the service.

Logging

Usually logs can be viewed through journalctl:

journalctl -u relay.service -f

If you are using a Windows machine, then it’s useful to specify a log output location during install:

.\relay.exe service install -c C:\config.yaml --logs-output C:\relay.log

Upgrade process

If the executable has write permissions, then to update it you only need to restart the service. Otherwise, follow these steps:

  1. Stop the service and uninstall it.
  2. Download the new binary following installation instructions for your platform.
  3. Install and start the service.