mirror of
https://github.com/luxfi/explorer-v1.git
synced 2026-10-30 19:34:59 +00:00
4.2 KiB
4.2 KiB
Aligning with Blockscout Upstream
This document shows how each network fork can stay aligned with Blockscout upstream while maintaining their own customizations.
Blockscout's Network Configuration Pattern
Blockscout organizes network configurations in environment files. Each network should follow this pattern:
1. Environment File Structure
Create .env files in docker-compose/envs/ following Blockscout's naming:
# Backend configuration
common-blockscout.env
# Frontend configuration
common-frontend.env
# Microservices
common-stats.env
common-smart-contract-verifier.env
common-visualizer.env
common-user-ops-indexer.env
2. Standard Environment Variables
Use Blockscout's standard variable names:
Backend (common-blockscout.env)
# Network Identity
CHAIN_ID=96369
COIN=LUX
COIN_NAME=LUX
# RPC Configuration
ETHEREUM_JSONRPC_VARIANT=geth
ETHEREUM_JSONRPC_HTTP_URL=http://your-rpc-endpoint
ETHEREUM_JSONRPC_TRACE_URL=http://your-rpc-endpoint
ETHEREUM_JSONRPC_WS_URL=ws://your-rpc-endpoint
# Database
DATABASE_URL=postgresql://user:pass@host:5432/dbname
# API Configuration
API_V2_ENABLED=true
API_V1_READ_METHODS_DISABLED=false
API_V1_WRITE_METHODS_DISABLED=false
Frontend (common-frontend.env)
# Network Display
NEXT_PUBLIC_NETWORK_NAME=LUX Network
NEXT_PUBLIC_NETWORK_SHORT_NAME=LUX
NEXT_PUBLIC_NETWORK_ID=96369
NEXT_PUBLIC_NETWORK_CURRENCY_NAME=LUX
NEXT_PUBLIC_NETWORK_CURRENCY_SYMBOL=LUX
NEXT_PUBLIC_NETWORK_CURRENCY_DECIMALS=18
# Branding
NEXT_PUBLIC_NETWORK_LOGO=https://your-domain/logo.svg
NEXT_PUBLIC_NETWORK_ICON=https://your-domain/icon.svg
# Features
NEXT_PUBLIC_IS_TESTNET=false
NEXT_PUBLIC_HAS_USER_OPS=true
3. Docker Compose Structure
Keep the standard Blockscout docker-compose structure:
version: '3.9'
services:
backend:
image: ghcr.io/blockscout/blockscout:${DOCKER_TAG:-latest}
env_file:
- ./envs/common-blockscout.env
ports:
- 4000:4000
frontend:
image: ghcr.io/blockscout/frontend:${DOCKER_TAG:-latest}
env_file:
- ./envs/common-frontend.env
ports:
- 3000:3000
# Other services...
4. Minimal Modifications
To stay aligned with upstream:
- Don't modify core files - Use environment variables for configuration
- Don't change service names - Keep backend, frontend, stats, etc.
- Use standard ports - Or remap them in docker-compose
- Follow naming conventions - For environment variables and files
5. Custom Branding
Add branding without modifying code:
# Logo files
frontend/public/images/
├── network_logo.svg
├── network_logo_dark.svg
└── favicon.ico
# Set via environment
NEXT_PUBLIC_NETWORK_LOGO=/images/network_logo.svg
NEXT_PUBLIC_NETWORK_LOGO_DARK=/images/network_logo_dark.svg
6. Contributing Back to Upstream
If your network becomes popular, you can contribute to Blockscout:
-
Create a PR to add your network config:
blockscout/frontend/configs/envs/.env.yournetwork -
Add to their featured networks:
blockscout/frontend/configs/featured-networks/yournetwork.json -
Submit chain metadata:
{ "name": "YourNetwork", "chainId": 12345, "shortName": "YN", "networkId": 12345, "nativeCurrency": { "name": "YourToken", "symbol": "YT", "decimals": 18 } }
Benefits of This Approach
- Easy Updates: Pull latest Blockscout without conflicts
- Standard Tooling: Use Blockscout's deployment scripts
- Community Support: Get help from Blockscout community
- Professional: Shows you follow industry standards
- Future-proof: Ready for Blockscout's new features
Example: Adding a New Network
# 1. Fork Blockscout
git clone https://github.com/yourorg/blockscout-fork
# 2. Create your env files
cp docker-compose/envs/common-blockscout.env.example docker-compose/envs/common-blockscout.env
# Edit with your network details
# 3. Add simple run scripts
cat > scripts/run-mainnet.sh << 'EOF'
#!/bin/bash
cd docker-compose
docker-compose up -d
EOF
# 4. Deploy
./scripts/run-mainnet.sh
This way, each network maintains their own fork but stays compatible with Blockscout's ecosystem.