Links

ENV Variables

The following are backend related variables. Frontend common ENVs for the new frontend are available here.
Additional information related to certain variables is available on the ansible deployment page.
You will find deprecated ENV vars on the Deprecated ENV Variables page.

Set ENV Variables with CLI

Use the export command to set variables. For example:
$ export ETHEREUM_JSONRPC_VARIANT=nethermind
$ export COIN=POA
$ export NETWORK=POA

Example ENV Variables Set

The following variables are set for the Gnosis Chain Blockscout Instance. Note that some variables are not included as they contain private information which should not be exposed.
Gnosis-Chain-Variables.txt
6KB
Binary

Full ENV Variables CSV file

Last updated 4 August, 2023.
Blockscout-ENV-variables.csv
50KB
Text

Time format

Can be set in format 1h for 1 hour, 1m for 1 minute, 1s or 1 for 1 second, 1ms for 1 millisecond
Note: Before release 5.1.2, all environment variables of time format supported only integers in seconds (without dimensions) as values.

Available ENV Variables

This table is horizontally scrollable, version information is located in the last column. ENVs are listed by category:

General

Variable
Required
Description
Default
Version
Need recompile
DATABASE_URL
Variable to define the Postgres Database endpoint.
(empty)
all
ETHEREUM_JSONRPC_VARIANT
Tells the application which RPC Client the node is using (i.e. erigon, geth, nethermind, besu, or ganache) (See Client Settings for more info)
ganache
all
ETHEREUM_JSONRPC_HTTP_URL
The RPC endpoint used to fetch blocks, transactions, receipts, tokens.
localhost:8545
all
DATABASE_READ_ONLY_API_URL
Variable to define the Postgres Database read-only replica endpoint. If it is provided, most of the read queries from API v2 and UI would go through this endpoint.
(empty)
all
ETHEREUM_JSONRPC_TRACE_URL
The RPC endpoint specifically for the Erigon/Geth/Nethermind/Besu client used by trace_block and trace_replayTransaction. This can be used to designate a tracing node.
localhost:8545
all
ETHEREUM_JSONRPC_WS_URL
The WebSockets RPC endpoint used to subscribe to the newHeads subscription alerting the indexer to fetch new blocks.
ws://localhost:8546
all
ETHEREUM_JSONRPC_TRANSPORT
Specifies the transport for Blockscout to connect to the Ethereum Node. Available transports are http and ipc. If ipc is selected, also set IPC_PATH variable.
http
v3.1.0+
ETHEREUM_JSONRPC_HTTP_INSECURE
If true is set, allows insecure HTTP connections to the archive node. For instance, it allows to bypass expired SSL certificate at the archive node endpoint. Implemented in (#6573)[https://github.com/blockscout/blockscout/pull/6573]
(empty)
v5.0.0+
ETHEREUM_JSONRPC_HTTP_TIMEOUT
Timeout for ethereum json rpc http requests in seconds. Implemented in (#7089)[https://github.com/blockscout/blockscout/pull/7089]
60
v5.1.2+
ETHEREUM_JSONRPC_USER
User in basic auth for JSON RPC endpoint. Implemented in (#6897)[https://github.com/blockscout/blockscout/pull/6897]
(empty)
v5.1.2+
ETHEREUM_JSONRPC_PASSWORD
Password in basic auth for JSON RPC endpoint. Implemented in (#6897)[https://github.com/blockscout/blockscout/pull/6897]
(empty)
v5.1.2+
ETHEREUM_JSONRPC_HTTP_HEADERS
Custom headers for JSON RPC endpoint in form of json object, example: {"x-api-key": "nbvkhadvnbkdfav", "x-id": "ndjkfvndfkjv"}. Implemented in (#7898)[https://github.com/blockscout/blockscout/pull/7898]
(empty)
v5.2.1+
NETWORK
Environment variable for the main EVM network such as Ethereum or POA.
POA
all
SUBNETWORK
Environment variable for the subnetwork such as Core or Sokol Network. This will be displayed as selected in the chains list dropdown.
POA Sokol
all
IPC_PATH
Path to the IPC file of the running node if IPC transport is chosen.
(empty)
v2.1.1+
NETWORK_PATH
Used to set a network path other than what is displayed in the root directory. An example would be to add /eth/mainnet/ to the root directory.
/
all
BLOCKSCOUT_HOST
Host for API endpoint examples.
localhost
v2.1.0+
BLOCKSCOUT_PROTOCOL
Url scheme for blockscout.
in prod env https is used, in dev env http is used
v2.1.0+
SECRET_KEY_BASE
Use mix phx.gen.secret to generate a new Secret Key Base string to protect production assets.
(empty)
all
CHECK_ORIGIN
Used to check the origin of requests when the origin header is present. It defaults to false. In case of true, it will check against the host value.
false
all
PORT
Default port the application runs on is 4000.
4000
all
COIN
The coin here is checked via the CoinGecko API to obtain USD prices on graphs and other areas of the UI.
POA
all
COIN_NAME
Displayed name of the coin. Also used for "Add chain to MetaMask" button and for Account functionality as native coin name in the email letters for watch list.
(empty)
v4.1.2+
EMISSION_FORMAT
Should be set to POA if you have block emission identical to POA Network. This env var is used only if CHAIN_SPEC_PATH is set.
DEFAULT
v2.0.4+
CHAIN_SPEC_PATH
Chain specification path (absolute file system path or URL) to import block emission reward ranges and genesis account balances from. Geth- and OpenEthereum-style specs are supported.
(empty)
v2.0.4+
SUPPLY_MODULE
This environment variable is used by the xDai Chain/RSK in order to tell the application how to calculate the total supply of the chain. Available values are TokenBridge, RSK
(empty)
all
POOL_SIZE
Variable to define the number of database connections allowed excluding read-only API endpoints requests.
50
all
POOL_SIZE_API
Variable to define the number of database connections allowed for read-only API endpoints requests.
50
v4.1.0+
ECTO_USE_SSL
Production environment variable to use SSL on Ecto queries.
true
all
HEART_BEAT_TIMEOUT
Production environment variable to restart the application in the event of a crash.
30
all
HEART_COMMAND
Production environment variable to restart the application in the event of a crash.
(empty)
all
ELIXIR_VERSION
Elixir version to install on the node before Blockscout deploy. It is used in bash script in Terraform / Ansible deployment script
(empty)
all
GRAPHIQL_TRANSACTION
Default transaction hash in a sample query to GraphiQL.
(empty)
v1.2.0+
DISABLE_WEBAPP
If true, endpoints to webapp are hidden (compile-time). Also, enabling it makes notifications go through db_notify
false
v2.0.3+
API_V1_READ_METHODS_DISABLED
If true, read-only endpoints to API v1 are hidden (compile-time).
false
v5.1.5+
API_V1_WRITE_METHODS_DISABLED
If true, write endpoints to API v1 are hidden (compile-time).
false
v5.1.5+
WEBAPP_URL
Link to web application instance, e.g. protocol://host/path
(empty)
v2.0.3+
API_URL
Link to API instance, e.g. protocol://host/path
(empty)
v2.0.3+
CHECKSUM_ADDRESS_HASHES
If set to true, redirects to checksummed version of address hashes.
true
v3.1.0+
CHECKSUM_FUNCTION
Defines checksum address function. 2 available values: rsk, eth
eth
v2.0.1+
RESTRICTED_LIST
A comma-separated list of addresses to enable restricted access to them.
(empty)
v3.3.3+
RESTRICTED_LIST_KEY
A key to access addresses listed inRESTRICTED_LIST variable. Can be passed via query param to the page's URL: ?key=...
(empty)
v3.3.3+
CHAIN_ID
Chain ID of the network. For instance, 100 in the case of xDai chain.
(empty)
v3.7.0+
JSON_RPC
JSON RPC endpoint of the chain for the WalletConnect integration. Implemented in #4931
(empty)
v4.1.0+
HEALTHY_BLOCKS_PERIOD
New blocks indexed max delay in /health API endpoint. Time format. Implemented in #2294
5 m
v2.0.2+
NEW_TAGS
Add public tag labels. More info in #6316
(empty)
v5.0.0+
CUSTOM_CONTRACT_ADDRESSES_${tag_name}
Specify addresses for some label. More info in #6316
(empty)
v5.0.0+
API_V2_ENABLED
Enable API V2. Implemented in #6361
(empty)
v5.0.0+
TOKEN_ID_MIGRATION_FIRST_BLOCK
Bottom block for token id migration. Implemented in #6391
0
v5.0.0+
TOKEN_ID_MIGRATION_CONCURRENCY
Number of workers performing the token id migration. Implemented in #6391
1
v5.0.0+
TOKEN_ID_MIGRATION_BATCH_SIZE
Interval of token transfer block numbers processed by a token id migration worker at a time. Implemented in #6391
500
v5.0.0+
SESSION_COOKIE_DOMAIN
Value of this env will be added to domain of session cookie. Implemented in #6544
(empty)
v5.0.0+
DECODE_NOT_A_CONTRACT_CALLS
Allows to decode contract calls directed to addresses which are not contracts. Implemented in #6541
false
v5.1.0+
EIP_1559_ELASTICITY_MULTIPLIER
EIP-1559 elasticity multiplier. Implemented in #7253
2
v5.1.3+
ETHEREUM_JSONRPC_FALLBACK_HTTP_URL
Fallback JSON RPC HTTP url. Implemented in #7246
(empty)
v5.1.4+
ETHEREUM_JSONRPC_FALLBACK_TRACE_URL
Fallback JSON RPC trace url. Implemented in #7246
(empty)
v5.1.4+
API_SENSITIVE_ENDPOINTS_KEY
API key to protect some sensitive endpoints. Implemented in #7355
(empty)
v5.1.5+
ETHEREUM_JSONRPC_WAIT_PER_TIMEOUT
Wait time for each recent timeout from node. Implemented in #8292
20s
v5.2.3+

Indexer management

Variable
Required
Description
Default
Version
BLOCK_TRANSFORMER
Transformer for blocks: base or clique.
base
v1.3.4+
DISABLE_INDEXER
If true, indexer application doesn't run.
false
v2.0.3+
INDEXER_HIDE_INDEXING_PROGRESS_ALERT
If true, indexer progress alert will be disabled even if initial catchup indexing is still in place. Implemented in #7360.
false
v5.1.5+
INDEXER_DISABLE_PENDING_TRANSACTIONS_FETCHER
If true, pending transactions fetcher is disabled.
false
v4.1.2+
INDEXER_DISABLE_INTERNAL_TRANSACTIONS_FETCHER
If true, internal transactions fetcher is disabled.
false
v4.1.2+
INDEXER_DISABLE_BLOCK_REWARD_FETCHER
if true, block rewards fetcher is disabled.
false
v4.1.3+
INDEXER_DISABLE_ADDRESS_COIN_BALANCE_FETCHER
If true, coin balances fetcher is disabled.
false
v4.1.3+
INDEXER_DISABLE_CATALOGED_TOKEN_UPDATER_FETCHER
If true, cataloged tokens metadata fetcher is disabled.
false
v4.1.3+
INDEXER_MEMORY_LIMIT
Memory soft limit for the indexer.
1Gb
v4.1.3+
INDEXER_EMPTY_BLOCKS_SANITIZER_BATCH_SIZE
Batch size for empty block sanitizer (re-fetcher).
100
v4.1.3+
INDEXER_CATCHUP_BLOCKS_BATCH_SIZE
Batch size for blocks catchup fetcher. Implemented in #6196.
10
v5.0.0+
INDEXER_CATCHUP_BLOCKS_CONCURRENCY
Concurrency for blocks catchup fetcher. Implemented in #6196.
10
v5.0.0+
INDEXER_DISABLE_EMPTY_BLOCKS_SANITIZER
Empty blocks sanitizer is disabled if true
false
v5.1.2+
DISABLE_REALTIME_INDEXER
If true, realtime fetcher doesn't run
false
v4.1.6+
FIRST_BLOCK
The block number, where import of blocks by catchup fetcher begins from.
0
v1.3.8+
LAST_BLOCK
The block number, where import of blocks by catchup fetcher stops.
(empty)
v2.0.3+
TRACE_FIRST_BLOCK
The block number, where indexing of internal transactions begins from.
0
v4.1.0+
TRACE_LAST_BLOCK
The block number, where indexing of internal transactions stops.
(empty)
v4.1.0+
BLOCK_RANGES
Block ranges to import by catchup fetcher. Implemented in #5783
v4.1.7+
FETCH_REWARDS_WAY
Tells the application how to calculate block rewards, by fetching via json_rpc (trace_block) or manual by block params (manual).
trace_block
v4.1.4+
ETHEREUM_JSONRPC_DEBUG_TRACE_TRANSACTION_TIMEOUT
Timeout for debug_traceTransaction JSON RPC method request in case of geth archive node. Supported time formats: https://pkg.go.dev/time#ParseDuration. Introduced in #5505
5s
v4.1.3+
ETHEREUM_JSONRPC_DISABLE_ARCHIVE_BALANCES
If true, all the requests with the method eth_getBalance with any block as parameter but latest are ignored. Implemented in #6001
false
v5.0.0+
ETHEREUM_JSONRPC_PENDING_TRANSACTIONS_TYPE
Defines which method will be used for fetching pending transactions: default - default method for fetching internal transactions for current ETHEREUM_JSONRPC_VARIANT, geth - txpool_content method will be used, parity - parity_pendingTransactions will be used. Implemented in #6001
default
v5.0.0+
INDEXER_INTERNAL_TRANSACTIONS_BATCH_SIZE
Batch size for internal transactions fetcher. Implemented in #6450.
10
v5.0.0+
INDEXER_INTERNAL_TRANSACTIONS_CONCURRENCY
Concurrency for internal transactions fetcher. Implemented in #6450.
4
v5.0.0+
INDEXER_INTERNAL_TRANSACTIONS_INDEXING_FINISHED_THRESHOLD
In the case when the 1st tx in the chain already has internal transactions, If the number of blocks in pending_block_operations is less than the value in this env var, Blockscout will consider, that indexing of internal transactions finished, otherwise, it will consider, that indexing is still taking place and the indexing banner will appear at the top. Implemented in #7576.
1000
v5.2.0+
INDEXER_BLOCK_REWARD_BATCH_SIZE
Batch size for block reward fetcher. Implemented in #6952.
10
v5.1.2+
INDEXER_BLOCK_REWARD_CONCURRENCY
Concurrency for block reward fetcher. Implemented in #6952.
4
v5.1.2+
INDEXER_RECEIPTS_BATCH_SIZE
Batch size for transaction receipts fetcher. Implemented in #6454.
250
v5.0.0+
INDEXER_RECEIPTS_CONCURRENCY
Concurrency for transaction receipts fetcher. Implemented in #6454.
10
v5.0.0+
INDEXER_COIN_BALANCES_BATCH_SIZE
Batch size for coin balances fetcher. Implemented in #6454.
500
v5.0.0+
INDEXER_COIN_BALANCES_CONCURRENCY
Concurrency for coin balances fetcher. Implemented in #6454.
4
v5.0.0+
INDEXER_TOKEN_CONCURRENCY
Concurrency for token fetcher. Implemented in #8167.
10
v5.2.2
INDEXER_TOKEN_BALANCES_BATCH_SIZE
Batch size for token balances fetcher. Implemented in #7439.
100
v5.1.5+
INDEXER_TOKEN_BALANCES_CONCURRENCY
Concurrency for token balances fetcher. Implemented in #8167.
10
v5.2.2
INDEXER_TX_ACTIONS_ENABLE
If true, transaction action indexer is active. Implemented in #6582.
false
v5.1.0+
INDEXER_TX_ACTIONS_MAX_TOKEN_CACHE_SIZE
Maximum number of items in an internal cache of tx actions indexing process (to limit memory consumption). Implemented in #6582.
100000
v5.1.0+
INDEXER_TX_ACTIONS_REINDEX_FIRST_BLOCK
The first block of a block range for historical indexing or reindexing of tx actions. Implemented in #6582.
(empty)
v5.1.0+
INDEXER_TX_ACTIONS_REINDEX_LAST_BLOCK
The last block of a block range for historical indexing or reindexing of tx actions. Implemented in #6582.
(empty)
v5.1.0+
INDEXER_TX_ACTIONS_REINDEX_PROTOCOLS
Comma-separated names of protocols which should be indexed or reindexed on historical blocks defined by the range. Example: uniswap_v3,zkbob - only these protocols will be indexed or reindexed for the defined block range. If the value is empty string (or not defined), all supported protocols will be indexed/reindexed. This option is not applicable to realtime and catchup fetchers (it always indexes all supported protocols). Implemented in #6582.
(empty)
v5.1.0+
INDEXER_TX_ACTIONS_AAVE_V3_POOL_CONTRACT
Pool contract address for Aave v3 protocol. If not defined, Aave transaction actions are ignored by the indexer. Implemented in #7185.
(empty)
v5.1.3+
INDEXER_TX_ACTIONS_UNISWAP_V3_FACTORY_CONTRACT
UniswapV3Factory contract address. Implemented in #7312.
0x1F98431c8aD98523631AE4a59f267346ea31F984
v5.1.4+
INDEXER_TX_ACTIONS_UNISWAP_V3_NFT_POSITION_MANAGER_CONTRACT
NonfungiblePositionManager contract address for Uniswap v3. Implemented in #7312.
0xC36442b4a4522E871399CD717aBDD847Ab11FE88
v5.1.4+
INDEXER_CATCHUP_MISSING_RANGES_BATCH_SIZE
Batch size for missing ranges collector. Implemented in #6583.
100000
v5.0.0+
MIN_MISSING_BLOCK_NUMBER_BATCH_SIZE
Batch size for min missing block number updater. Implemented in #6583.
100000
v5.0.0+
INDEXER_INTERNAL_TRANSACTIONS_TRACER_TYPE
Tracer type for debug_traceTransaction request for geth-like nodes. Possible values are: js to use custom Blockscout js tracer, call_tracer to use built-in callTracer geth tracer, opcode to use built-in Struct/opcode logger geth tracer, polygon_edge to work with Polygon edge nodes. Implemented in #6721, #7513
call_tracer
v5.1.0+
INDEXER_TOKEN_INSTANCE_RETRY_REFETCH_INTERVAL
Interval between attempts to fetch token instance metadata. Time format. Implemented in #7286.
24h
v5.1.4+
INDEXER_TOKEN_INSTANCE_RETRY_CONCURRENCY