Install Stellar Horizon API: Quick Start Tutorial

We will start with a fresh Ubuntu 20.04 LTS instance. It is important to use any of the recent LTS Ubuntu instances if you wish to use the packages maintained by Stellar Development Foundation.

First we will do our usual server setup tasks such as updating packages, setting hostname, firewall, and others. This is beyond the scope of this guide, but some basics to get you started (as root or with sudo):

apt update
apt upgrade
hostnamectl set-hostname <your server hostname>

Next, the Stellar package repositories need to be added, along with installing the necessary packages to run our Horizon API server. Following commands should be ran as root, or with sudo.

wget -qO - https://apt.stellar.org/SDF.asc | sudo apt-key add -

echo "deb https://apt.stellar.org $(lsb_release -cs) stable" | sudo tee -a /etc/apt/sources.list.d/SDF.list

systemctl mask stellar-core

apt update
apt install stellar-horizon stellar-horizon-postgres stellar-core

After installing above components, we will ensure that postgresql starts with the instance, as well as stellar-horizon. Plus we will ensure stellar-core does not start, as horizon will instantiate its own instance of stellar-core (stellar-captive-core).

systemctl stop stellar-core # in case it was running
systemctl disable stellar-core #make sure it won't start on reboot
systemctl enable postgresql #make sure our DB will start with the instance
systemctl restart postgresql  #ensure DB is currently running

There is a minor adjustment that needs to be made to the stellar-horizon systemd startup script. It is to set the working directory, so that the captive core components can be created properly by the stellar user. We will set the working directory to the stellar users home directory, which is already configured for you to be at /var/lib/stellar

nano /lib/systemd/system/stellar-horizon.service

Adjust the [Service] block by adding WorkingDirectory like this:

[Service]
User=stellar
Group=stellar
LimitNOFILE=8192
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=stellar-horizon
EnvironmentFile=/etc/default/stellar-horizon
WorkingDirectory=/var/lib/stellar
ExecStart=/usr/bin/stellar-horizon
ExecReload=/bin/kill -HUP $MAINPID
KillMode=process
Restart=on-failure
RestartPreventExitStatus=255
Type=simple

Now let’s add the following configs. Horizon uses (by default) /etc/default/stellar-horizon for its configuration, in the form of Environment variables. Update your file at this location to match this:

Next we will add the Stellar captive core config, which will allow our minimal instance of stellar core to connect to well known validators for handling our requests. We mention the location of this file in the above config, so please ensure the location of this config matches location mentioned above. This will be at /etc/default/stellar-captive-core-stub.toml if you are following the guide and adjusted your stellar-horizon file as mentioned above.

Next we should be able to start Horizon and allow it to start ingesting data so it can serve API requests! As root:

systemctl enable stellar-horizon
systemctl restart stellar-horizon

Now let’s confirm it is working as it should:

systemctl status stellar-horizon

And upon visiting your stellar horizon server at port 8000, you should be welcomed with a list of all available endpoints. It will take some time before the Horizon API server is usable as it has to ingest data first, but within 5-15 minutes or so, you should be 100% ready to go!

If anything in this guide does not work on a fresh Ubuntu install, please be sure to let me know in the comments so I can update the post accordingly.