proxmox/docs/08-monitoring/BLOCKSCOUT_CONFIGURATION_GUIDE.md

Blockscout Configuration Guide - Complete Setup

Last Updated: 2026-01-31
Document Version: 1.0
Status: Active Documentation

---

Container: VMID 5000 (192.168.11.140)
Chain ID: 138
Status: Ready for configuration

---

Quick Start

Since you're already SSH'd into the container, run these commands:

1. Install/Copy Configuration Script

# If you have the script file, copy it:
# Or run commands directly below

2. Configure and Start Blockscout

Run the configuration commands (see below) or use the script.

---

Complete Configuration Steps

Step 1: Check Current Status

# Check Docker
docker --version
docker-compose --version || docker compose version

# Check existing containers
docker ps -a

# Check if Blockscout directory exists
ls -la /opt/blockscout
ls -la /root/blockscout

Step 2: Create/Update docker-compose.yml

# Navigate to Blockscout directory
cd /opt/blockscout  # or /root/blockscout if that's where it is

# Create docker-compose.yml with correct settings
cat > docker-compose.yml <<'EOF'
version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    container_name: blockscout-postgres
    environment:
      POSTGRES_USER: blockscout
      POSTGRES_PASSWORD: blockscout
      POSTGRES_DB: blockscout
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped
    networks:
      - blockscout-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U blockscout"]
      interval: 10s
      timeout: 5s
      retries: 5

  blockscout:
    image: blockscout/blockscout:latest
    container_name: blockscout
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      - DATABASE_URL=postgresql://blockscout:blockscout@postgres:5432/blockscout
      - ETHEREUM_JSONRPC_HTTP_URL=http://192.168.11.250:8545
      - ETHEREUM_JSONRPC_WS_URL=ws://192.168.11.250:8546
      - ETHEREUM_JSONRPC_TRACE_URL=http://192.168.11.250:8545
      - ETHEREUM_JSONRPC_VARIANT=besu
      - CHAIN_ID=138
      - COIN=ETH
      - BLOCKSCOUT_HOST=192.168.11.140
      - BLOCKSCOUT_PROTOCOL=http
      - SECRET_KEY_BASE=$(openssl rand -hex 64)
      - POOL_SIZE=10
      - ECTO_USE_SSL=false
    ports:
      - "4000:4000"
    volumes:
      - blockscout-data:/app/apps/explorer/priv/static
    restart: unless-stopped
    networks:
      - blockscout-network

volumes:
  postgres-data:
  blockscout-data:

networks:
  blockscout-network:
    driver: bridge
EOF

# Generate secret key and update
SECRET_KEY=$(openssl rand -hex 64)
sed -i "s|SECRET_KEY_BASE=\$(openssl rand -hex 64)|SECRET_KEY_BASE=${SECRET_KEY}|" docker-compose.yml

Step 3: Start Services

# Stop existing containers
docker-compose down 2>/dev/null || docker compose down 2>/dev/null || true

# Start PostgreSQL first
docker-compose up -d postgres || docker compose up -d postgres

# Wait for PostgreSQL to be ready
echo "Waiting for PostgreSQL..."
for i in {1..30}; do
    if docker exec blockscout-postgres pg_isready -U blockscout >/dev/null 2>&1; then
        echo "PostgreSQL ready!"
        break
    fi
    sleep 2
done

# Start Blockscout
docker-compose up -d blockscout || docker compose up -d blockscout

Step 4: Configure Nginx

# Install Nginx if not installed
apt-get update
apt-get install -y nginx

# Create Nginx config
cat > /etc/nginx/sites-available/blockscout <<'EOF'
server {
    listen 80;
    listen [::]:80;
    server_name 192.168.11.140 explorer.d-bis.org;

    client_max_body_size 100M;

    location / {
        proxy_pass http://localhost:4000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
    }

    location /api {
        proxy_pass http://localhost:4000/api;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
    }

    location /health {
        proxy_pass http://localhost:4000/api/health;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        access_log off;
    }
}
EOF

# Enable site
ln -sf /etc/nginx/sites-available/blockscout /etc/nginx/sites-enabled/blockscout
rm -f /etc/nginx/sites-enabled/default

# Test and reload
nginx -t && systemctl reload nginx
systemctl enable nginx
systemctl start nginx

Step 5: Verify

# Check containers
docker ps

# Check logs
docker logs blockscout
docker logs blockscout-postgres

# Test endpoints
curl http://localhost:4000/api/health
curl http://localhost/
curl http://192.168.11.140/

---

Configuration Settings Reference

Environment Variables

Variable	Value	Description
CHAIN_ID	138	Chain ID for d-bis network
RPC_URL	http://192.168.11.250:8545	HTTP RPC endpoint
WS_URL	ws://192.168.11.250:8546	WebSocket RPC endpoint
BLOCKSCOUT_HOST	192.168.11.140	Host IP address
DATABASE_URL	postgresql://blockscout:blockscout@postgres:5432/blockscout	PostgreSQL connection
ETHEREUM_JSONRPC_VARIANT	besu	RPC variant (Besu)

---

Troubleshooting

Check Container Logs

# Blockscout logs
docker logs -f blockscout

# PostgreSQL logs
docker logs blockscout-postgres

# All containers
docker-compose logs -f

Restart Services

cd /opt/blockscout  # or wherever docker-compose.yml is
docker-compose restart

Check RPC Connectivity

curl -X POST http://192.168.11.250:8545 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

---

Last Updated: $(date)