Running the Alert System

The following instructions describe running the Bitcoin SV Alert System using tools available in most mainstream Linux distributions. The assumption has been made that you are using a Bourne-like shell such as bash.

Infrastructure Considerations

Hosting an Alert System that uses a P2P IPFS layer on some infrastructure providers like Hetzner could lead to problems due to their abuse detection mechanisms. The IPFS layer involves port scanning to find peers, which Hetzner might mistake for malicious activity. This can trigger Hetzner's automated systems to block or restrict your account.

Since continuous operation is crucial for an Alert System, Hetzner's sensitivity to port scanning makes it an unsuitable hosting choice for such an application. Please note that the Alert System only requires RPC access to a node and as such can run on different infrastructure than your node. Make sure to configure the proper security rules to restrict access to the RPC interface, for example using Hetzner's firewall rules.

Running the Alert System

In order to run the Alert System for each given network, there are some environment variables that should be set.

Server Configuration

Environment VariableDescriptionExample Values


The environment to start the Alert System with. Set this to the network type you'd like to run on.





Path to a valid bitcoin.conf file. Alert System will read the RPC configuration values from this file to communicate to the Bitcoin node.



If this is set to true, then the Alert System will not attempt to verify the provided RPC credentials on startup. This is useful if bitcoind is not running.



Webhook URL for the Alert System to send human readable alert messages to. See later in the doc for details.


Port for libp2p to serve on. (Defaults to 9906)



Port for the local apiserver to serve on. (Defaults to 3000)



Rather than logging to stdout, configure the server to log directly to a file on disk.



Path to where the SQLite3 database for the alert-system should be saved. (Defaults to ./alert_system_datastore.db


With the proper environment variables set, the alert-system binary can be run directly without any arguments.

ALERT_SYSTEM_BITCOIN_CONFIG_PATH=/home/user/bitcoin-data/bitcoin.conf \


To start the install of the Alert System, make sure you use an account that can use su or sudo to install software into directories owned by the root user.

Download the zipped release of your choosing from the Github release page, for this example we are using 0.1.1 which is the latest release at the time of writing:


Locate the file you downloaded and extract it using the unzip command:

# sudo apt-get install unzip -y
mkdir -p alert-system-0.1.1
unzip -d alert-system-0.1.1

Create a symbolic link from a new directory called alert-system to the alert-system-0.1.1 directory you just made by unzipping for easier use and updates:

ln -s alert-system-0.1.1 alert-system

To run the alert system, pass in the location of the bitcoind configuration file so that it can connect over RPC:

cd alert-system
# Example based on user
ALERT_SYSTEM_BITCOIN_CONFIG_PATH=/home/user/bitcoin-data/bitcoin.conf \

Create the alert-system.service file:

sudo vim /etc/systemd/system/alert-system.service
Description=BSV Alert System service
# Make sure to replace username
# Make sure to replace username

Then start:

sudo systemctl start alert-system.service
sudo systemctl enable alert-system.service

Follow the logs using journalctl

sudo journalctl -xeu alert-system.service -f

Multiple nodes and remote Alert Systems

If you are hosting the Alert System on the same host as the bitcoind, make sure only 1 instance of the Alert System is running on that host.

You can host multiple Alert Systems on a single instance or Kubernetes cluster, but then you will need to make sure they all run on a unique port and take care of any firewall considerations. For these setups it's easier to use a config.json to define the port and RPC credentials for the nodes. An example config can be found in the alert-system repo at app/config/envs/mainnet.json.

ALERT_SYSTEM_CONFIG_FILEPATH=path/to/file/config.json ./alert-system

Docker images for the Alert System can be found on Docker Hub.

Last updated