🍀Upgrade Guide (v7.0)

We continue to add new features and functionality to Blockscout and recommend updating your instance with each new release. You can check compatibility between your current backend and frontend versions in the Compatibility Matrix.

If it has been a while since your last upgrade, we recommend performing incremental upgrades to ensure proper performance. For example if you are running backend v6.9.0, first upgrade to v6.10.0 prior to upgrading to the latest 7.0 version. This reduces downtime and ensures all breaking changes are handled.

Getting Started

This guide walks through the process of updating Blockscout to backend v7.0.2 and frontend v1.38.0 (March, 2025) from v6.10.X. If you have questions about a different upgrade, contact us in Discord. Breaking changes follow the instructions.

1) Update backend ENV variables

Backend variable renaming only applies to the 6.10.X -> 7.0.X update. If you are performing a more extensive update, please check renaming & deprecations from the release notes of every minor release (6.8.0, 6.9.0 etc) within your update range.

Newly renamed variables include the MIGRATIONprefix. If a variable contained MIGRATION in the name previously, it has been moved to the beginning of the variable. Expand below to see all variables you need to rename.

Backend Renamed Variables

Old name	New name
TOKEN_ID_MIGRATION_FIRST_BLOCK	MIGRATION_TOKEN_ID_FIRST_BLOCK
TOKEN_ID_MIGRATION_CONCURRENCY	MIGRATION_TOKEN_ID_CONCURRENCY
TOKEN_ID_MIGRATION_BATCH_SIZE	MIGRATION_TOKEN_ID_BATCH_SIZE
SHRINK_INTERNAL_TRANSACTIONS_BATCH_SIZE	MIGRATION_SHRINK_INTERNAL_TRANSACTIONS_BATCH_SIZE
SHRINK_INTERNAL_TRANSACTIONS_CONCURRENCY	MIGRATION_SHRINK_INTERNAL_TRANSACTIONS_CONCURRENCY
TOKEN_INSTANCE_OWNER_MIGRATION_CONCURRENCY	MIGRATION_TOKEN_INSTANCE_OWNER_CONCURRENCY
TOKEN_INSTANCE_OWNER_MIGRATION_BATCH_SIZE	MIGRATION_TOKEN_INSTANCE_OWNER_BATCH_SIZE
TOKEN_INSTANCE_OWNER_MIGRATION_ENABLED	MIGRATION_TOKEN_INSTANCE_OWNER_ENABLED
DENORMALIZATION_MIGRATION_BATCH_SIZE	MIGRATION_DENORMALIZATION_BATCH_SIZE
DENORMALIZATION_MIGRATION_CONCURRENCY	MIGRATION_DENORMALIZATION_CONCURRENCY
TOKEN_TRANSFER_TOKEN_TYPE_MIGRATION_BATCH_SIZE	MIGRATION_TOKEN_TRANSFER_TOKEN_TYPE_BATCH_SIZE
TOKEN_TRANSFER_TOKEN_TYPE_MIGRATION_CONCURRENCY	MIGRATION_TOKEN_TRANSFER_TOKEN_TYPE_CONCURRENCY
SANITIZE_INCORRECT_NFT_BATCH_SIZE	MIGRATION_SANITIZE_INCORRECT_NFT_BATCH_SIZE
SANITIZE_INCORRECT_NFT_CONCURRENCY	MIGRATION_SANITIZE_INCORRECT_NFT_CONCURRENCY
SANITIZE_INCORRECT_NFT_TIMEOUT	MIGRATION_SANITIZE_INCORRECT_NFT_TIMEOUT
SANITIZE_INCORRECT_WETH_BATCH_SIZE	MIGRATION_SANITIZE_INCORRECT_WETH_BATCH_SIZE
SANITIZE_INCORRECT_WETH_CONCURRENCY	MIGRATION_SANITIZE_INCORRECT_WETH_CONCURRENCY
SANITIZE_INCORRECT_WETH_TIMEOUT	MIGRATION_SANITIZE_INCORRECT_WETH_TIMEOUT
REINDEX_INTERNAL_TRANSACTIONS_STATUS_BATCH_SIZE	MIGRATION_REINDEX_INTERNAL_TRANSACTIONS_STATUS_BATCH_SIZE
REINDEX_INTERNAL_TRANSACTIONS_STATUS_CONCURRENCY	MIGRATION_REINDEX_INTERNAL_TRANSACTIONS_STATUS_CONCURRENCY
REINDEX_INTERNAL_TRANSACTIONS_STATUS_TIMEOUT	MIGRATION_REINDEX_INTERNAL_TRANSACTIONS_STATUS_TIMEOUT
FILECOIN_PENDING_ADDRESS_OPERATIONS_MIGRATION_BATCH_SIZE	MIGRATION_FILECOIN_PENDING_ADDRESS_OPERATIONS_BATCH_SIZE
FILECOIN_PENDING_ADDRESS_OPERATIONS_MIGRATION_CONCURRENCY	MIGRATION_FILECOIN_PENDING_ADDRESS_OPERATIONS_CONCURRENCY
ARBITRUM_DA_RECORDS_NORMALIZATION_MIGRATION_BATCH_SIZE	MIGRATION_ARBITRUM_DA_RECORDS_NORMALIZATION_BATCH_SIZE
ARBITRUM_DA_RECORDS_NORMALIZATION_MIGRATION_CONCURRENCY	MIGRATION_ARBITRUM_DA_RECORDS_NORMALIZATION_CONCURRENCY

2) Install backend

-> blockscout/blockscout:7.0.2

3) Install frontend

-> ghcr.io/blockscout/frontend:v1.38.0

Frontend Variable Updates

From	To	Example
NEXT_PUBLIC_ROLLUP_L1_BASE_URL NEXT_PUBLIC_ROLLUP_PARENT_CHAIN_NAME	NEXT_PUBLIC_ROLLUP_PARENT_CHAIN	current values NEXT_PUBLIC_ROLLUP_L1_BASE_URL =<L1-url> NEXT_PUBLIC_ROLLUP_PARENT_CHAIN_NAME =<chain-name> new values NEXT_PUBLIC_ROLLUP_PARENT_CHAIN={'name':'<chain-name>','baseUrl':'<L1-url>'}
NEXT_PUBLIC_RE_CAPTCHA_V3_APP_SITE_KEY	NEXT_PUBLIC_RE_CAPTCHA_APP_SITE_KEY
NEXT_PUBLIC_HOMEPAGE_PLATE_TEXT_COLOR NEXT_PUBLIC_HOMEPAGE_PLATE_BACKGROUND	NEXT_PUBLIC_HOMEPAGE_HERO_BANNER_CONFIG	current values NEXT_PUBLIC_HOMEPAGE_PLATE_BACKGROUND=<my-background> NEXT_PUBLIC_HOMEPAGE_PLATE_TEXT_COLOR=<my-text-color> new values NEXT_PUBLIC_HOMEPAGE_HERO_BANNER_CONFIG={'background':['<my-background>'],'text_color':['<my-text-color>']}

Deprecated Frontend Variables

Deprecated
NEXT_PUBLIC_AUTH0_CLIENT_ID
NEXT_PUBLIC_AUTH_URL
NEXT_PUBLIC_LOGOUT_URL
FAVICON_GENERATOR_API_KEY
NEXT_PUBLIC_SENTRY_DSN
SENTRY_CSP_REPORT_URI
NEXT_PUBLIC_SENTRY_ENABLE_TRACING

4) Install microservices

-> Stats microservice ghcr.io/blockscout/stats:v2.5.0.

-> Use the latest tag to install any other microservices used with your instance https://github.com/blockscout/blockscout-rs

Breaking Changes

/api/v1/health, /api/v1/health/liveness, /api/v1/health/readiness have been removed in favor of /api/health/** endpoints.

/api/v2/addresses/:address_hash returns 200 instead 404 for valid hashes which are not in the DB.

/api/v2/tokens/:token_hash/instances owner’s ens_domain_name property now preloads the ens domain name.

transaction hash and address hash are no longer mandatory in the txlistinternal API v1 endpoint

/metrics endpoint available on indexer pod (previously existed only on API pod)