Explorer v2.1 Upgrade Guide

This guide walks through a typical OpenScan.AI explorer upgrade — from pre-upgrade backups to post-upgrade verification. Use it as a template for any minor or major version upgrade of a self-hosted deployment.

Before You Start

Read the release notes for the version you’re installing; note any required migrations or reindex steps.
Schedule a maintenance window if your explorer serves production traffic. Expect brief API downtime.
Back up the database:

docker compose exec postgres pg_dump -U explorer explorer_db > backup-$(date +%F).sql

Note your current version so you can roll back:

docker compose images

Step 1 — Pull the New Images

docker compose pull

Step 2 — Stop the Stack Gracefully

Stop the API and frontend first so users stop hitting the database, then the indexer, then the database:

docker compose stop frontend api
docker compose stop indexer

Step 3 — Run Migrations

Apply any database migrations shipped with the release:

docker compose run --rm indexer ./bin/migrate

If the release requires a reindex of specific data (the release notes will say so), schedule it now — reindexes run in the background while the explorer stays up.

Step 4 — Start the Upgraded Stack

docker compose up -d

Watch the indexer catch up to the chain head:

docker compose logs -f indexer

Step 5 — Verify

Open the explorer UI and confirm the latest block matches your chain node’s height.
Query the API directly:

curl "http://localhost:4000/api/v2/blocks" | head

Check a recent transaction page and a token page for decoding errors.
Review the verification checklist.

Rollback

If anything looks wrong:

docker compose down
# restore the pre-upgrade database
cat backup-YYYY-MM-DD.sql | docker compose exec -T postgres psql -U explorer explorer_db
# pin image tags back to the previous version in docker-compose.yml
docker compose up -d