> ## Documentation Index
> Fetch the complete documentation index at: https://developers.stellar.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring

> For production, we recommend running Stellar RPC with a TOML configuration file rather than CLI flags. This is similar to creating a configuration file for Stellar-Core as we did previously. For example, using our docker image:

For production, we recommend running Stellar RPC with a [TOML](https://toml.io/en) configuration file rather than CLI flags. This is similar to creating a configuration file for Stellar-Core as we did previously. For example, using [our docker image](https://hub.docker.com/r/stellar/stellar-rpc):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
docker run -p 8001:8001 -p 8000:8000 \
-v <CONFIG_FOLDER>:/config stellar/stellar-rpc \
--config-path <RPC_CONFIG_FILENAME>
```

Use this [Stellar RPC subcommand](https://github.com/stellar/stellar-rpc/blob/main/cmd/stellar-rpc/README.md#configuring-and-running-rpc-server) to generate a starter configuration file:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
docker run stellar/stellar-rpc:latest gen-config-file > stellar-rpc-config.toml
```

The resulting configuration should look like this:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Admin endpoint to listen and serve on. WARNING: this should not be accessible
# from the Internet and does not use TLS. "" (default) disables the admin server
# ADMIN_ENDPOINT = ""

# Populates database with `history-retention-window` ledgers synchronously on
# startup. This defaults to a week of ledgers if unspecified
# BACKFILL = false

# path to additional configuration for the Stellar Core configuration file used
# by captive core. It must, at least, include enough details to define a quorum
# set
# CAPTIVE_CORE_CONFIG_PATH = ""

# Storage location for Captive Core bucket data
CAPTIVE_CORE_STORAGE_PATH = "/"

# establishes how many ledgers exist between checkpoints, do NOT change this
# unless you really know what you are doing
CHECKPOINT_FREQUENCY = 64

# configures classic fee stats retention window expressed in number of ledgers
CLASSIC_FEE_STATS_RETENTION_WINDOW = 10

# SQLite DB path
DB_PATH = "stellar_rpc.sqlite"

# Default cap on the amount of events included in a single getEvents response
DEFAULT_EVENTS_LIMIT = 100

# Default cap on the amount of ledgers included in a single getLedgers response
DEFAULT_LEDGERS_LIMIT = 50

# Default cap on the amount of transactions included in a single getTransactions
# response
DEFAULT_TRANSACTIONS_LIMIT = 50

# Endpoint to listen and serve on
ENDPOINT = "localhost:8000"

# The friendbot URL to be returned by getNetwork endpoint
# FRIENDBOT_URL = ""

# comma-separated list of stellar history archives to connect with
HISTORY_ARCHIVE_URLS = []

# configures history retention window for transactions and events, expressed in
# number of ledgers, the default value is 120960 which corresponds to about 7
# days of history
HISTORY_RETENTION_WINDOW = 120960

# Ingestion Timeout when bootstrapping data (checkpoint and in-memory
# initialization) and preparing ledger reads
INGESTION_TIMEOUT = "50m0s"

# format used for output logs (json or text)
# LOG_FORMAT = "text"

# minimum log severity (debug, info, warn, error) to log
LOG_LEVEL = "info"

# Maximum amount of events allowed in a single getEvents response
MAX_EVENTS_LIMIT = 10000

# The maximum duration of time allowed for processing a getEvents request. When
# that time elapses, the rpc server would return -32001 and abort the request's
# execution
MAX_GET_EVENTS_EXECUTION_DURATION = "10s"

# The maximum duration of time allowed for processing a getFeeStats request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_GET_FEE_STATS_EXECUTION_DURATION = "5s"

# The maximum duration of time allowed for processing a getHealth request. When
# that time elapses, the rpc server would return -32001 and abort the request's
# execution
MAX_GET_HEALTH_EXECUTION_DURATION = "5s"

# The maximum duration of time allowed for processing a getLatestLedger request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_GET_LATEST_LEDGER_EXECUTION_DURATION = "5s"

# The maximum duration of time allowed for processing a getLedgers request. When
# that time elapses, the rpc server would return -32001 and abort the request's
# execution
MAX_GET_LEDGERS_EXECUTION_DURATION = "10s"

# The maximum duration of time allowed for processing a getLedgerEntries
# request. When that time elapses, the rpc server would return -32001 and abort
# the request's execution
MAX_GET_LEDGER_ENTRIES_EXECUTION_DURATION = "5s"

# The maximum duration of time allowed for processing a getNetwork request. When
# that time elapses, the rpc server would return -32001 and abort the request's
# execution
MAX_GET_NETWORK_EXECUTION_DURATION = "5s"

# The maximum duration of time allowed for processing a getTransactions request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_GET_TRANSACTIONS_EXECUTION_DURATION = "5s"

# The maximum duration of time allowed for processing a getTransaction request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_GET_TRANSACTION_EXECUTION_DURATION = "5s"

# The maximum duration of time allowed for processing a getVersionInfo request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_GET_VERSION_INFO_EXECUTION_DURATION = "5s"

# maximum ledger latency (i.e. time elapsed since the last known ledger closing
# time) considered to be healthy (used for the /health endpoint)
MAX_HEALTHY_LEDGER_LATENCY = "30s"

# Maximum amount of ledgers allowed in a single getLedgers response
MAX_LEDGERS_LIMIT = 200

# The max request execution duration is the predefined maximum duration of time
# allowed for processing a request. When that time elapses, the server would
# return 504 and abort the request's execution
MAX_REQUEST_EXECUTION_DURATION = "25s"

# The maximum duration of time allowed for processing a sendTransaction request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_SEND_TRANSACTION_EXECUTION_DURATION = "15s"

# The maximum duration of time allowed for processing a simulateTransaction
# request. When that time elapses, the rpc server would return -32001 and abort
# the request's execution
MAX_SIMULATE_TRANSACTION_EXECUTION_DURATION = "15s"

# Maximum amount of transactions allowed in a single getTransactions response
MAX_TRANSACTIONS_LIMIT = 200

# Specifies the desired Stellar network, 'pubnet', 'testnet', or 'futurenet'.
# NETWORK = ""

# Network passphrase of the Stellar network transactions should be signed for.
# Commonly used values are "Test SDF Future Network ; October 2022", "Test SDF
# Network ; September 2015" and "Public Global Stellar Network ; September 2015"
# NETWORK_PASSPHRASE = ""

# Enable debug information in preflighting (provides more detailed errors). It
# should not be enabled in production deployments.
PREFLIGHT_ENABLE_DEBUG = true

# Number of workers (read goroutines) used to compute preflights for the
# simulateTransaction endpoint. Defaults to the number of CPUs.
PREFLIGHT_WORKER_COUNT = 8

# Maximum number of outstanding preflight requests for the simulateTransaction
# endpoint. Defaults to the number of CPUs.
PREFLIGHT_WORKER_QUEUE_SIZE = 8

# Maximum number of outstanding GetEvents requests
REQUEST_BACKLOG_GET_EVENTS_QUEUE_LIMIT = 1000

# Maximum number of outstanding GetFeeStats requests
REQUEST_BACKLOG_GET_FEE_STATS_QUEUE_LIMIT = 100

# Maximum number of outstanding GetHealth requests
REQUEST_BACKLOG_GET_HEALTH_QUEUE_LIMIT = 1000

# Maximum number of outstanding GetLatestsLedger requests
REQUEST_BACKLOG_GET_LATEST_LEDGER_QUEUE_LIMIT = 1000

# Maximum number of outstanding getLedgers requests
REQUEST_BACKLOG_GET_LEDGERS_QUEUE_LIMIT = 1000

# Maximum number of outstanding GetLedgerEntries requests
REQUEST_BACKLOG_GET_LEDGER_ENTRIES_QUEUE_LIMIT = 1000

# Maximum number of outstanding GetNetwork requests
REQUEST_BACKLOG_GET_NETWORK_QUEUE_LIMIT = 1000

# Maximum number of outstanding GetTransactions requests
REQUEST_BACKLOG_GET_TRANSACTIONS_QUEUE_LIMIT = 1000

# Maximum number of outstanding GetTransaction requests
REQUEST_BACKLOG_GET_TRANSACTION_QUEUE_LIMIT = 1000

# Maximum number of outstanding GetVersionInfo requests
REQUEST_BACKLOG_GET_VERSION_INFO_QUEUE_LIMIT = 1000

# Maximum number of outstanding requests
REQUEST_BACKLOG_GLOBAL_QUEUE_LIMIT = 5000

# Maximum number of outstanding SendTransaction requests
REQUEST_BACKLOG_SEND_TRANSACTION_QUEUE_LIMIT = 500

# Maximum number of outstanding SimulateTransaction requests
REQUEST_BACKLOG_SIMULATE_TRANSACTION_QUEUE_LIMIT = 100

# The request execution warning threshold is the predetermined maximum duration
# of time that a request can take to be processed before a warning would be
# generated
REQUEST_EXECUTION_WARNING_THRESHOLD = "5s"

# configures soroban inclusion fee stats retention window expressed in number of
# ledgers
SOROBAN_FEE_STATS_RETENTION_WINDOW = 50

# HTTP port for Captive Core to listen on (0 disables the HTTP server)
STELLAR_CAPTIVE_CORE_HTTP_PORT = 11626

# HTTP port for Captive Core to listen on for high-performance queries like
# /getledgerentry (must not conflict with CAPTIVE_CORE_HTTP_PORT)
STELLAR_CAPTIVE_CORE_HTTP_QUERY_PORT = 11628

# Size of ledger history in Captive Core's high-performance query server (don't
# touch unless you know what you are doing)
STELLAR_CAPTIVE_CORE_HTTP_QUERY_SNAPSHOT_LEDGERS = 4

# path to stellar core binary
STELLAR_CORE_BINARY_PATH = "/usr/bin/stellar-core"

# Timeout used when submitting requests to stellar-core
STELLAR_CORE_TIMEOUT = "2s"

# URL used to query Stellar Core (local captive core by default)
# STELLAR_CORE_URL = ""

# Enable strict toml configuration file parsing. This will prevent unknown
# fields in the config toml from being parsed.
# STRICT = false

# Fetch historical ledgers from the datastore if they're not available locally. This entry should be followed by a datastore configuration.
# SERVE_LEDGERS_FROM_DATASTORE = false
```

> [!NOTE]
>
> Example datastore configurations can be found on the [data lake integration page](https://developers.stellar.org/docs/data/apis/rpc/admin-guide/data-lake-integration.md).

Note that the above generated configuration contains the default values and you need to substitute them with proper values to run the image. For instance, when using a container, it is recommended to create a volume for the Captive Core and RPC persistent storage and point `CAPTIVE_CORE_STORAGE_PATH` and `DB_PATH` to it accordingly.

Then, you should create a configuration file for [Stellar Core](https://github.com/stellar/stellar-core). You can find sample configuration files for [Testnet](https://github.com/stellar/go-stellar-sdk/blob/main/ingest/ledgerbackend/configs/captive-core-testnet.cfg) and [Pubnet](https://github.com/stellar/go-stellar-sdk/blob/main/ingest/ledgerbackend/configs/captive-core-pubnet.cfg)

When using docker, you should create and mount a volume [mount a volume](https://docs.docker.com/storage/volumes) on your container where the above configuration is stored.

If you are running locally on a unix-style machine, you could create a folder in your home directory called `~/rpc-config`

```
cd ~
mkdir rpc-config
```

Then you would add the following config files to that local directory:

* soroban-rpc-config.toml
* stellar-captive-core.cfg

Then you would mount that volume using by adding the following parameter: `-v /Users/<USERNAME>/test-rpc-config:/opt/stellar` to your `docker run` command.

Your running container would mount that volume at the path `/opt/stellar`

## Backfilling History on Startup

Set `BACKFILL = true` to populate the database with a trailing window of history synchronously on startup, before live ingestion begins. This option was added in RPC v25.1.0 and defaults to `false`.

`HISTORY_RETENTION_WINDOW` sets the target size of that window. The default is `120960` ledgers, which is about 7 days.

RPC treats this value as a target, not an exact count. Datastore coverage, ledgers already in the local database, and checkpoint boundaries can each reduce what the node fetches.

`BACKFILL` also requires datastore serving. Set `SERVE_LEDGERS_FROM_DATASTORE = true`. If you enable `BACKFILL` alone, RPC fails to start with this error:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
backfill requires serving ledgers from datastore to be enabled. See the `--serve-ledgers-from-datastore` flag
```

To set up the datastore, see [Data Lake Integration](https://developers.stellar.org/docs/data/apis/rpc/admin-guide/data-lake-integration.md). That page also explains which requests the datastore serves directly.

## Next Step

After installation is complete, you are now ready to proceed to [Running RPC](https://developers.stellar.org/docs/data/apis/rpc/admin-guide/running.md)!