Skip to content

These new docs are in beta. Please submit bugs to GitHub issues.


Configuring

Parameters

Horizon can be configured by both command line flags or environment variables. To see the list of command line flags that are available, their default values, and their corresponding environmental variables for your version of Horizon, run:

horizon --help

When you run the command above, you’ll see that Horizon defines a large number of flags; however, only a handful are required:

flagenvvarexample
--db-urlDATABASE_URLpostgres://localhost/horizon_testnet
--captive-core-config-append-pathCAPTIVE_CORE_CONFIG_APPEND_PATH/etc/default/stellar-captive-core-stub.toml
--stellar-core-urlSTELLAR_CORE_URLhttp://localhost:11626
--stellar-core-binary-pathSTELLAR_CORE_BINARY_PATH/usr/bin/stellar-core
  • The most important parameter, --db-url, specifies the Horizon database, and its value should be a valid PostgreSQL Connection URI.
  • The second parameter, --captive-core-config-append-path, points to a Captive Core configuration stub. This stub file only requires a few fields (explained below) to get up and running.
  • The final parameter, --stellar-core-binary-path, is a filesystem path to a Stellar Core binary. Since Horizon will search your PATH for stellar-core by default, if your environment is configured appropriately, you won’t even need to pass this.

Note that Horizon will perform ingestion by default as of v2.0; if you want to have certain nodes dedicated exclusively to fulfilling requests, you should set --enable-captive-core-ingestion=false.

Specifying command line flags every time you invoke Horizon can be cumbersome, so we recommend using environment variables. There are many tools you can use to manage them: we recommend either direnv or dotenv. However, if you installed via the package manager, the provided stellar-horizon-cmd wrapper will actually import a configuration from /etc/default/stellar-horizon and set up the environment accordingly.

Preparing the Database

Before running the Horizon server, you must first prepare the Horizon database. This database will be used for all of the information produced by Horizon, notably historical information about successful transactions that have occurred on the stellar network.

To prepare a database for Horizon’s use, you must first ensure the database is blank. It’s easiest to simply create a new database on your PostgreSQL server specifically for Horizon’s use. Next, you must install the schema by running horizon db init. Remember to use the appropriate command line flags or environment variables to configure Horizon as explained above. This command will log any errors that occur.

Postgres Configuration

It is recommended to set random_page_cost=1 in Postgres configuration if you are using SSD storage. With this setting, Query Planner will make a better use of indices, expecially for JOIN queries. We’ve noticed a huge speed improvement for some queries with this setting.

Configuring Captive Core

While a full Stellar Core node requires a complex configuration with lots of possible fields, the Captive Core configuration stub can be kept extremely barebones. The rest of the configuration will be generated automagically at runtime. Here’s is a minimal working example, operating under the assumption that you want to connect to the testnet and trust SDF’s validators exclusively:

TOML
[[HOME_DOMAINS]]
HOME_DOMAIN="testnet.stellar.org"
QUALITY="HIGH"

[[VALIDATORS]]
NAME="sdf_testnet_1"
HOME_DOMAIN="testnet.stellar.org"
PUBLIC_KEY="GDKXE2OZMJIPOSLNA6N6F2BVCI3O777I2OOC4BV7VOYUEHYX7RTRYA7Y"
ADDRESS="core-testnet1.stellar.org"
HISTORY="curl -sf http://history.stellar.org/prd/core-testnet/core_testnet_001/{0} -o {1}"

[[VALIDATORS]]
NAME="sdf_testnet_2"
HOME_DOMAIN="testnet.stellar.org"
PUBLIC_KEY="GCUCJTIYXSOXKBSNFGNFWW5MUQ54HKRPGJUTQFJ5RQXZXNOLNXYDHRAP"
ADDRESS="core-testnet2.stellar.org"
HISTORY="curl -sf http://history.stellar.org/prd/core-testnet/core_testnet_002/{0} -o {1}"

[[VALIDATORS]]
NAME="sdf_testnet_3"
HOME_DOMAIN="testnet.stellar.org"
PUBLIC_KEY="GC2V2EFSXN6SQTWVYA5EPJPBWWIMSD2XQNKUOHGEKB535AQE2I6IXV2Z"
ADDRESS="core-testnet3.stellar.org"
HISTORY="curl -sf http://history.stellar.org/prd/core-testnet/core_testnet_003/{0} -o {1}"

(For the remainder of this guide, we’ll assume this stub lives at /etc/default/stellar-captive-core-stub.toml.)

You can install the stellar-captive-core package to simplify configuration here, but the minimum required fields are the [[HOME_DOMAINS]] and a set of [[VALIDATORS]], so if you wanted to configure your instance for the public network, you would simply replace the above with their pubnet equivalents. As inspiration, here is the set of domains and validators that SDF configures on the pubnet.

Remote Captive Core

As mentioned earlier, we provide a library that wraps a Captive Core instance in an HTTP API that Horizon can consume remotely.

Configuring Core

We’ll need to configure the Captive Core environment. The required parameters include the above, the configuration stub, as well as a few others:

flagenvvarexample
--network-passphraseNETWORK_PASSPHRASETest SDF Network ; September 2015
--history-archive-urlsHISTORY_ARCHIVE_URLShttps://history.stellar.org/prd/core-testnet/core_testnet_001,https://history.stellar.org/prd/core-testnet/core_testnet_002

For example, if you wanted to rely on SDF for history archives and connect to the test network, you might prepare your environment as follows:

bash
export NETWORK_PASSPHRASE='Test SDF Network ; September 2015'
export HISTORY_ARCHIVE_URLS='https://history.stellar.org/prd/core-testnet/core_testnet_001'
export DATABASE_URL='postgres://postgres:[email protected]:5432/horizon?sslmode=disable'
export CAPTIVE_CORE_CONFIG_APPEND_PATH=/etc/default/stellar-captive-core-stub.toml

(We suppose, of course, that the above PostgreSQL URI is a correctly-configured database.)

Configuring Horizon

On the local Horizon instance (i.e. the one htat will connect to the above-configured remote Captive Core), rather than passing the --captive-core-config-append-path, --stellar-core-url, and --stellar-core-binary-path parameters described above, we only need a single parameter:

flagenvvarexample
--remote-captive-core-urlREMOTE_CAPTIVE_CORE_URLhttp://10.0.0.42:8000

This URL should point to a running Captive Core API. Note that nothing prohibits this from being a localhost URL, if you want Captive Core running in a separate process from Horizon or are running a containerized setup, for example.

Last updated Apr. 12, 2021

Next Up: Running
Page Outline