Deployment
Upgrade Guide (V7.0 & V8.0)
Guide for upgrading Blockscout to major versions 7.0 and 8.0.
🚗 Autoscout is now available, providing a simple one-click explorer deployment with Blockscout’s optimized hosting infrastructure. Use it for early testing, modifications, and launching a full production-grade explorer. Get Started Now and have your explorer up-and-running in minutes.
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. Please update to v7.0 before updating to v8.0. Follow the same process below replacing v7 with the latest front and backend repositories.
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.
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
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.23) Install frontend
-> ghcr.io/blockscout/frontend:v1.38.0Frontend Variable Updates
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 |
|---|
| 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 thelatest 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)