proxmox/docs/08-monitoring/BLOCKSCOUT_CONFIGURATION_GUIDE.md

Blockscout Configuration Guide - Complete Setup

Last Updated: 2026-04-04
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?sslmode=disable
      - 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=50
      - POOL_SIZE_API=50
      - DATABASE_QUEUE_TARGET=5s
      - INDEXER_DISABLE_PENDING_TRANSACTIONS_FETCHER=true
      - 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

# If legacy docker-compose crashes with KeyError: 'ContainerConfig',
# remove the old container and start Blockscout directly:
docker rm -f blockscout 2>/dev/null || true
docker run -d \
  --name blockscout \
  --restart unless-stopped \
  --network blockscout_blockscout-network \
  -p 4000:4000 \
  -e DATABASE_URL=postgresql://blockscout:blockscout@postgres:5432/blockscout?sslmode=disable \
  -e ETHEREUM_JSONRPC_HTTP_URL=http://192.168.11.250:8545 \
  -e ETHEREUM_JSONRPC_WS_URL=ws://192.168.11.250:8546 \
  -e ETHEREUM_JSONRPC_TRACE_URL=http://192.168.11.250:8545 \
  -e ETHEREUM_JSONRPC_VARIANT=besu \
  -e CHAIN_ID=138 \
  -e COIN=ETH \
  -e BLOCKSCOUT_HOST=192.168.11.140 \
  -e BLOCKSCOUT_PROTOCOL=http \
  -e SECRET_KEY_BASE="$SECRET_KEY" \
  -e POOL_SIZE=50 \
  -e POOL_SIZE_API=50 \
  -e DATABASE_QUEUE_TARGET=5s \
  -e INDEXER_DISABLE_PENDING_TRANSACTIONS_FETCHER=true \
  -e ECTO_USE_SSL=false \
  -v blockscout_blockscout-data:/app/apps/explorer/priv/static \
  blockscout/blockscout:latest \
  bin/blockscout start

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

• POOL_SIZE=50 and POOL_SIZE_API=50: recommended baseline for the public Chain 138 explorer on VMID 5000. The older POOL_SIZE=10 profile is too small under current indexer plus public API load.
• DATABASE_QUEUE_TARGET=5s: lets Blockscout wait longer before dropping DB work during bursty indexing.
• INDEXER_DISABLE_PENDING_TRANSACTIONS_FETCHER=true: keeps one noisy fetcher off by default; it reduced queue pressure during the April 4, 2026 E2E repair.

Troubleshooting Hot Path

• If /api/v2/stats, /api/v2/blocks, or /api/v2/transactions intermittently return 500, check docker logs blockscout for DBConnection.ConnectionError before changing nginx.
• If logs show connection not available and request was dropped from queue, raise pool sizes and queue target first.
• If logs show tcp recv (idle): closed, prefer the local Docker-network Postgres path (postgres:5432) over the VM host :6432 HAProxy hop on VMID 5000, then keep the larger Blockscout pools in place.
• If the legacy docker-compose binary throws KeyError: 'ContainerConfig', prefer docker compose or a temporary docker run recovery instead of repeatedly retrying the old binary.

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)