Build from Source (CLI)

Build the OpenScan.AI explorer stack from source on a Linux server. This guide provides full control over versions and configuration and is ideal for production deployments and contributors.

Prerequisites

• Ubuntu 22.04 LTS (or similar), 8+ GB RAM, SSD storage
• Docker and Docker Compose plugin
• Git
• A synced EVM node with JSON-RPC and tracing enabled (see Chain Node Layer)

Install Docker if needed:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Step 1 — Clone the Repository

git clone https://github.com/OpenScanAI/openscan.git
cd openscan

Step 2 — Configure the Environment

Copy the example environment file and edit it:

cp .env.example .env

Key settings:

# Chain connection
ETHEREUM_JSONRPC_HTTP_URL=http://your-chain-node:8545
ETHEREUM_JSONRPC_TRACE_URL=http://your-chain-node:8545
CHAIN_ID=50                      # e.g. 50 for XDC Network

# Database
DATABASE_URL=postgresql://explorer:CHANGE_ME@postgres:5432/explorer_db

# Public URLs
NEXT_PUBLIC_API_HOST=explorer.yourchain.example
NEXT_PUBLIC_NETWORK_NAME="Your Chain"

Step 3 — Build the Images

docker compose build

This compiles the indexer, API, and frontend from source. Expect the first build to take 15–30 minutes.

Step 4 — Initialize the Database

docker compose up -d postgres
docker compose run --rm indexer ./bin/migrate

Step 5 — Start the Stack

docker compose up -d

The indexer begins backfilling history immediately. Follow progress:

docker compose logs -f indexer

Step 6 — Verify

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

Once curl returns recent blocks and the UI at http://localhost:3000 renders, the build is complete. Run through the full verification checklist before exposing the explorer publicly.

Updating

git pull
docker compose build
docker compose up -d

See Network Upgrades for safe upgrade procedure.