Skip to content

Commit

Permalink
grammar in Configuration
Browse files Browse the repository at this point in the history
  • Loading branch information
@briwylde08
briwylde08 committed Jan 17, 2024
1 parent 7127215 commit 93f7377
Showing 1 changed file with 34 additions and 36 deletions.
70 changes: 34 additions & 36 deletions docs/run-platform-server/configuring.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,29 +5,27 @@ sidebar_position: 30

import { Alert } from "@site/src/components/Alert";

Pre-requisites:
## Prerequisites

- You have identified the [Installation](./installing.mdx) method for host system:
- You have identified the [installation](./installing.mdx) method for the host system:

For bare metal, you have two executables: `stellar-horizon` and `stellar-core` both on host OS' `$PATH`.
- For bare metal, you have two executables: `stellar-horizon` and `stellar-core` both on host OS' `$PATH`.
- For running Horizon image with Docker daemon, you will use the [stellar/stellar-horizon](https://hub.docker.com/r/stellar/stellar-horizon) hosted on Docker Hub. You have already pulled the stellar/stellar-horizon image via `docker pull stellar/stellar-horizon:<tag_version>` onto host. This image contains the `stellar-horizon` and `stellar-core` within.
- For Kubernetes with [Horizon Helm Chart](https://github.com/stellar/helm-charts/tree/main/charts/horizon), you have followed the [Install Horizon with Helm Chart](./installing.mdx#helm-chart-installation).

For running horizon image with docker daemon, you will use the [stellar/stellar-horizon](https://hub.docker.com/r/stellar/stellar-horizon) hosted on dockerhub. You have already pulled the stellar/stellar-horizon image via `docker pull stellar/stellar-horizon:<tag_version>` onto host. This image contains the `stellar-horizon` and `stellar-core` within.

For Kubernetes with [Horizon Helm Chart](https://github.com/stellar/helm-charts/tree/main/charts/horizon), you have followed the [Install Horizon with Helm Chart](./installing.mdx#helm-chart-installation).

- [Initialize Database](#initialize-horizon-database)
- [Initialize database](#initialize-horizon-database)

You are now ready to identify the configuration parameters needed to perform three important roles:

- **serving read only API requests** via a regular web-based HTTP API, and
- **ingesting ledgers** from core nodes of a Stellar network to keep its world-view up to date, and
- **submitting transactions** via a regular web-based HTTP API, forwarding the transaction submission request to the Stellar network.
- **Serving read-only API requests** via a regular web-based HTTP API;
- **Ingesting ledgers** from Core nodes of the Stellar network to keep its world-view up to date;
- **Submitting transactions** via a regular web-based HTTP API, forwarding the transaction submission request to the Stellar network.

To perform these roles, you can choose from one of two of the deployment modes that follow. Each has its own configuration parameters.
To perform these roles, you can choose from one of two deployment modes below (single instance deployment or multiple instance deployment). Each has its own configuration parameters.

## Single Instance Deployment

You run `stellar-horizon` in a single o/s process and it will perform all three roles at same time.
Run `stellar-horizon` in a single o/s process and it will perform all three roles simultaneously.

| environment variable | example |
| ------------------------- | ----------------------------------- |
Expand All @@ -37,11 +35,11 @@ You run `stellar-horizon` in a single o/s process and it will perform all three

## Multiple Instance Deployment

In this scalable deployment variant, you run multiple instances of `stellar-horizon` and each performs a subset of the roles. This allows you to horizontally scale each of the role functions independently.
In this scalable deployment variant, you run multiple instances of `stellar-horizon`, each performing a subset of the roles. This allows you to horizontally scale each of the role functions independently.

### Ingestion Role Instance

You need to allocate **at least** one instance to perform ongoing ingestion to capture network activity. This will default to limiting storage of ingested network activity in the database to our recommendation of a sliding window of the last 30 days.
You must allocate **at least** one instance to perform ongoing ingestion to capture network activity. This will default to limiting storage of ingested network activity in the database to our recommendation of a sliding window of the last 30 days.

| environment variable | example |
| ------------------------- | ----------------------------------- |
Expand All @@ -52,7 +50,7 @@ You need to allocate **at least** one instance to perform ongoing ingestion to c

### API Role Instance

You can run none or multiple instances to serve read only API requests. Notice there is no need to define network settings here, as Horizon only reads from database.
You can run none or multiple instances to serve read-only API requests. Notice there is no need to define network settings here, as Horizon only reads from database.

| environment variable | example |
| -------------------- | ----------------------------------- |
Expand All @@ -62,11 +60,11 @@ You can run none or multiple instances to serve read only API requests. Notice t

### Transaction Submission Role Instance

You can run none or multiple instances to serve transaction submission requests. If you run an instance with transaction submission enabled, the horizon deployment is required to have at least one instance perform the ingestion role on the same database. Horizon transaction submission depends on this **live** ingestion taking place against the database in order to confirm tx submission status.
You can run none or multiple instances to serve transaction submission requests. If you run an instance with transaction submission enabled, the Horizon deployment is required to have at least one instance perform the ingestion role on the same database. Horizon transaction submission depends on this **live** ingestion taking place against the database in order to confirm tx submission status.

If ingestion is planned to be done on a separate instance, add `INGEST=false` on this instance, otherwise don't include the parameter, Horizon will default to `INGEST=true`. When a transaction submission enabled instance has `INGEST=true` effective, it will configure the related `STELLAR_CORE_URL` parameter automatically to use the internally launched captive core instance and the deployment does not need to set the configuration value explicitly.

If setting `INGEST=false`, then **must** define the `STELLAR_CORE_URL` variable on this transaction submission enabled instance, since there will be no internally hosted captive core instance as part of ingestion available to reference, instead the `STELLAR_CORE_URL` provides the ability to define the url of a core instance http port which horizon will send transaction submissions towards.
If setting `INGEST=false`, then **must** define the `STELLAR_CORE_URL` variable on this transaction submission enabled instance, since there will be no internally hosted captive core instance as part of ingestion available to reference, instead the `STELLAR_CORE_URL` provides the ability to define the URL of a core instance HTTP port which Horizon will send transaction submissions towards.

| environment variable | example |
| -------------------- | ----------------------------------- |
Expand All @@ -78,47 +76,47 @@ If setting `INGEST=false`, then **must** define the `STELLAR_CORE_URL` variable

- If you have configured your deployment to perform the ingestion role, then it is **strongly** recommended to review [Ingestion](./ingestion.mdx) first and [Filtering](./ingestion-filtering) second and factor that into configuration parameters to achieve best performance related to your application requirements before proceeding further.

- `DISABLE_TX_SUB`, optional, set as FALSE by default. Controls whether Horizon will accept HTTP requests to `/tx` API endpoint and forward to network. Refer to [Channel Accounts](../encyclopedia/channel-accounts.mdx) for some recommendations on optional client transaction submission optimizations.
- `DISABLE_TX_SUB`: optional, set as FALSE by default. Controls whether Horizon will accept HTTP requests to the `/tx` API endpoint and forward to the network. Refer to [Channel Accounts](../encyclopedia/channel-accounts.mdx) for some recommendations on optional client transaction submission optimizations.

- When set to FALSE, it requires **live** ingestion process to be running on the same database because Horizon depends on new ledgers from network to confirm a transaction submission status, Horizon will report startup error if it detects no **live** ingestion. Requires `INGEST=true` or `STELLAR_CORE_URL` be defined for access to a core instance.
- When set to FALSE, it requires **live** ingestion process to be running on the same database because Horizon depends on new ledgers from the network to confirm a transaction submission status, Horizon will report a startup error if it detects no **live** ingestion. Requires `INGEST=true` or `STELLAR_CORE_URL` to be defined for access to a Core instance.
- When transaction submission is disabled by setting it to TRUE, Horizon will return 405 on POSTs to /tx.

- `NETWORK`, optional, can be one of Stellar's public networks, 'pubnet', or 'testnet'. Triggers horizon to automatically set configurations for remaining horizon settings and generate the correct core toml/cfg settings. If you only need Horizon to connect to one of those public Stellar networks, this will take care of all related configuration.
- `NETWORK`: optional, can be one of Stellar's public networks, 'pubnet', or 'testnet'. Triggers Horizon to automatically set configurations for remaining Horizon settings and generate the correct core toml/cfg settings. If you only need Horizon to connect to one of those public Stellar networks, this will take care of all related configurations.

- If you want to connect Horizon to a different stellar network other than pubnet or testnet or override any of the defaults that `NETWORK` usage will initiate, the key envrionment variables that can be set are: `HISTORY_ARCHIVE_URLS`, `CAPTIVE_CORE_CONFIG_PATH`, `NETWORK_PASSPHRASE`, `CAPTIVE_CORE_STORAGE_PATH`, `STELLAR_CORE_URL`.
- If you want to connect Horizon to a different Stellar network other than pubnet or testnet or override any of the defaults that `NETWORK` usage will initiate, the key environment variables that can be set are: `HISTORY_ARCHIVE_URLS`, `CAPTIVE_CORE_CONFIG_PATH`, `NETWORK_PASSPHRASE`, `CAPTIVE_CORE_STORAGE_PATH`, `STELLAR_CORE_URL`.

- `DB_URL`, required, specifies the Horizon database. It's value follows this format: `dbname=<pg_dbname> user=<pg_user_name> password=<pg_user_pwd> host=<host_address>`
- `DB_URL`: required, specifies the Horizon database. It's value follows this format: `dbname=<pg_dbname> user=<pg_user_name> password=<pg_user_pwd> host=<host_address>`

- `LOG_LEVEL`, optional, can be one of 'info', 'error', 'debug'.
- `LOG_LEVEL`: optional, can be one of 'info', 'error', 'debug'.

- `HISTORY_RETENTION_COUNT`, optional, this determines the maximum sliding window of historical network data to retain on the database from ingestion. The value is expressed as absolute ledger count, which is an indirect way to define a duration of time, each ledger being approximately 5 seconds. It is defaulted to 0, which means it will not purge any history from database. To enact the recommended sliding window of one month, set this to 518400. Which is the approximate number of ledgers in 30 days. Refer to [Compute Resources](./prerequisites.mdx) for how database storage space is closely related to this setting.
- `HISTORY_RETENTION_COUNT`: optional, this determines the maximum sliding window of historical network data to retain on the database from ingestion. The value is expressed as absolute ledger count, which is an indirect way to define a duration of time, each ledger being approximately 5 seconds. It is defaulted to 0, which means it will not purge any history from the database. To enact the recommended sliding window of one month, set this to 518400, which is the approximate number of ledgers in 30 days. Refer to [Compute Resources](./prerequisites.mdx) for how database storage space is closely related to this setting.

- Horizon will create a sub-directory under the current working directory of the o/s process to store captive core runtime data files. Refer to [Prerequisites](./prerequisites.mdx) for the type and amount of storage recommended. You can override this location with the optional `CAPTIVE_CORE_STORAGE_PATH` environment variable, set to a directory on file system which captive core will store the runtime files.
- Horizon will create a sub-directory under the current working directory of the o/s process to store captive core runtime data files. Refer to [Prerequisites](./prerequisites.mdx) for the type and amount of storage recommended. You can override this location with the optional `CAPTIVE_CORE_STORAGE_PATH` environment variable, set to a directory on the file system where captive core will store the runtime files.

### Passing configurations to Horizon
### Passing Configurations to Horizon

The `stellar-horizon` binary searches process environment variables for configuration. Depending on how Horizon was installed, the method you perform to configure the process environment will differ:

- bare-metal
- non-package manager, use O/S environment variables to pass configurations. There are many tools you can use to manage them, such as [direnv](http://direnv.net/) or [dotenv](https://github.com/bkeepers/dotenv).
- [package manager](./installing.mdx#package-manager), the provided `stellar-horizon-cmd` wrapper will start a new process and create environment variables in the process from `/etc/default/stellar-horizon` and then launch the 'stellar-horizon' in the process, hence, to set configurations, edit the file at `/etc/default/stellar-horizon`.
- Bare metal
- Non-package manager: use O/S environment variables to pass configurations. There are many tools you can use to manage them, such as [direnv](http://direnv.net/) or [dotenv](https://github.com/bkeepers/dotenv).
- [Package manager](./installing.mdx#package-manager): the provided `stellar-horizon-cmd` wrapper will start a new process and create environment variables in the process from `/etc/default/stellar-horizon` and then launch the 'stellar-horizon' in the process, hence, to set configurations, edit the file at `/etc/default/stellar-horizon`.
<Alert>
This script invokes Horizon with the `stellar` user, so make sure that
permissions for the user are set up accordingly. The current working
directory should be writable for this user and the user should be able to
execute the `stellar-horizon` and `stellar-core` binaries; etc.
</Alert>
- containerized
- non-Helm, pass all configuration parameters to the horizon docker image as [docker environment variables](https://docs.docker.com/engine/reference/commandline/run/#env).
- Helm, pass all configuration parameters in the [Helm Install command] as a values file.(https://helm.sh/docs/helm/helm_install/)
- Containerized
- Non-Helm: pass all configuration parameters to the horizon docker image as [docker environment variables](https://docs.docker.com/engine/reference/commandline/run/#env).
- Helm: pass all configuration parameters in the [Helm install command](https://helm.sh/docs/helm/helm_install/) as a values file.

## Initialize Horizon Database

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

To prepare a database for Horizon's use, first ensure it is blank. It's easiest to create a new database on your PostgreSQL server specifically for Horizon's use. We recommend creating a new user(role) in postgres dedicated to Horizon's database and assigning that user(role) as the owner of this database.

To illustrate an example using `psql`, first login to database server using the `psql` command-line tool as a superuser, and then create the new user(role) and database for Horizon:
To illustrate an example using `psql`, first login to the database server using the `psql` command-line tool as a superuser, and then create the new user(role) and database for Horizon:

```
postgres=#
Expand All @@ -132,7 +130,7 @@ postgres=#

Additionally, you can set a password on your new `horizon` postgres user with `ALTER USER`.

Once completed, you can compose the full value of configuration parameter for db access `DATABASE_URL="dbname=horizon user=horizon password=<value_here> host=<address_of_pg_server>"`.
Once completed, you can compose the full value of the configuration parameter for db access `DATABASE_URL="dbname=horizon user=horizon password=<value_here> host=<address_of_pg_server>"`.

Next, execute the Horizon binary to install the schema onto the empty db from the command line. In this example, assume the current shell doesn't have `DATABASE_URL` in environment yet, so export it first into shell:

Expand Down

0 comments on commit 93f7377

Please sign in to comment.