Skip to content
Docs
Submit bugs here.
Docs

Please submit any typos you come across to GitHub issues.


Prerequisites

Horizon only has one true dependency: a PostgreSQL server that it uses to store data that has been processed and ingested from Stellar Core. Horizon requires PostgreSQL version >= 9.5.

As far as system requirements go, there are a few main things to keep in mind. Starting from version 2.0, Horizon must be run as a standalone service. A full Horizon build consists of three functions:

  1. ingesting data from the decentralized Stellar network,
  2. submitting transactions to the network, and
  3. serving API requests

The first two happen through Captive Core, a pared down, non-validating version of Stellar Core packaged directly into Horizon.

With these three functions in mind, you can also run Horizon in two different ways: real-time ingestion and historical catch-up:

  • Real-time ingestion is an “online” process: it involves keeping in sync with the live Stellar network state and digesting ledger data into a holistic view of the network. If you just want function (3) from above, you still need to do this.

  • Historical catch-up is an “offline” process: it lets you look into the past and catch up your Horizon instance to a given retention period (e.g. 30 days of history). Because it’s typically done offline and a one-time process, you can dedicate more compute power and configure parallel workers to catch up faster.

Historical Catch-up

In this scenario, the hardware specifications are more demanding than what is necessary for the day-to-day operation of real-time ingestion, but catch-up only needs to occur once.

However, the requirements will vary depending on your chosen retention period and desired catch-up speed. Note that most operators will not need full history, and as the network continues to grow, tracking full history will become increasingly prohibitive. As of late 2021, DB storage to support historical retention is growing at a rate of 0.8 TB / month. It is highly recommended to configure retention of only the history needed to support your functionality.

Requirements

Minimally, your disk storage type must be an SSD (e.g. NVMe, Direct Attached Storage) and your I/O must handle >15k iops (I/O operations per second). The following table breaks down hardware specifications for ingestion at different retention levels and performance tiers.

Note that each component can be scaled independently and for redundancy, in the manner of traditional n-tier systems which is covered later in Scaling. Ingestion can be sped up via configuring more Captive Core parallel workers (requiring more compute and RAM).

ComponentRetention Period
30 days90 days
Parallel worker count
(est. ingestion time)
6 workers (1 day)10 workers (1 day)
HorizonCPU: 10 cores (min: 6)
RAM: 64 GB (min: 32)
CPU: 16 (min: 8)
RAM: 128 GB (64)
DatabaseCPU: 16 cores (min: 8)
RAM: 64 GB (min: 32GB)
Storage: 2 TB
IOPS: 20K (min: 15K)
CPU: 16 (12)
RAM: 128 GB (64)
Storage: 4 TB
IOPS: 20K (15K)
Storage
(all same)
SSD (NVMe, Direct Attached Storage preferred)
AWS
(reference)
Captive Core: m5.2xlarge
Database: r5.2xlarge
Captive Core: m5.4xlarge
DB: r5.4xlarge

Real-Time Ingestion

In this scenario, the goal is just to stay in sync with the Stellar network for day-to-day operations.

There are two extremes to this spectrum: running a single private instance of Horizon for a specific application all the way up to a serious enterprise public instance of Horizon. In the former case, you’d run all three functions on a single machine and have low request volume; in the latter case, you’d have high-availability, redundancy, high request volume, full history, etc.

Requirements

The following table breaks down requirements along this spectrum; if you fall somewhere in between, interpolate the requirements accordingly.

CategoryPrivate InstanceEnterprise Public Instance
ComputeBoth API Service + Captive Core:
CPU: 4
RAM: 32 GB
API Service
CPU: 4
RAM: 8 GB
N instances, load balanced

Captive Core
CPU: 8
RAM: 256 GB
2 instances for redundancy
DatabaseCPU: 4
RAM: 32 GB
IOPS: 7k (min: 2.5k)
CPU: 32 - 64
RAM: 256 - 512 GB
IOPS: 20k (min: 15k)
2 HA instances: 1RO, 1RW
Storage (SSD)depends on retention period10 TB
AWS (reference)API Service + Captive Core
m5.2xlarge

Database
r5.2xlarge (ro)
r5.xlarge (rw)
API Service
c5.xlarge (n)

Captive Core
c5.2xlarge (x2)

Database r5.16xlarge (ro)
r5.8xlarge (rw)

Last updated May. 27, 2022