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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Blockscout logs
docker logs -f blockscout

# PostgreSQL logs
docker logs blockscout-postgres

# All containers
docker-compose logs -f
```

### Restart Services

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

### Check RPC Connectivity

```bash
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)