proxmox/docs/archive/fixes/BLOCKSCOUT_EXPLORER_FIX.md

# Blockscout Explorer Fix - Complete Solution

**Date**: $(date)  
**Status**: ✅ **FIX SCRIPTS CREATED**

---

## Issue Summary

The Blockscout explorer at `https://explorer.d-bis.org` was returning HTTP 522 (Connection Timeout) from Cloudflare, indicating the origin server was not reachable.

**Root Causes Identified:**
1. ❌ Nginx reverse proxy not installed/configured
2. ⚠️ Blockscout container may not exist (VMID 5000)
3. ⚠️ Blockscout service may not be running
4. ❌ Cloudflare DNS/tunnel not configured for explorer.d-bis.org

---

## ✅ Solutions Created

### 1. Nginx Installation Script

**File**: `scripts/install-nginx-blockscout.sh`

- Installs Nginx in the Blockscout container
- Configures reverse proxy on ports 80/443
- Proxies to Blockscout on port 4000
- Sets up SSL certificates (self-signed, can be replaced with Let's Encrypt)
- Configures proper headers and timeouts

### 2. Cloudflare Configuration Script

**File**: `scripts/configure-cloudflare-explorer.sh`

- Configures Cloudflare DNS for explorer.d-bis.org
- Creates/updates CNAME record pointing to tunnel
- Enables Cloudflare proxy (orange cloud)
- Provides instructions for tunnel route configuration

### 3. Complete Fix Script

**File**: `scripts/fix-blockscout-explorer.sh`

Comprehensive script that:
- ✅ Checks container status
- ✅ Starts Blockscout service if needed
- ✅ Installs and configures Nginx
- ✅ Verifies all services are running
- ✅ Provides testing instructions

### 4. Deployment and Fix Script

**File**: `scripts/deploy-and-fix-blockscout.sh`

Complete solution that:
- ✅ Deploys Blockscout container if it doesn't exist
- ✅ Runs all fix scripts
- ✅ Configures everything automatically

---

## 🚀 Deployment Instructions

### Option 1: Container Already Exists

If container VMID 5000 already exists:

```bash
cd /home/intlc/projects/proxmox
./scripts/fix-blockscout-explorer.sh
```

### Option 2: Deploy and Fix (Complete)

**On Proxmox Host (192.168.11.10):**

```bash
ssh root@192.168.11.10

cd /home/intlc/projects/proxmox
export VMID_EXPLORER_START=5000
export PUBLIC_SUBNET=192.168.11
./scripts/deploy-and-fix-blockscout.sh
```

**Or deploy manually then fix:**

```bash
# On Proxmox host
cd /home/intlc/projects/proxmox/smom-dbis-138-proxmox/scripts/deployment
export VMID_EXPLORER_START=5000
export PUBLIC_SUBNET=192.168.11
./deploy-explorer.sh

# Then run fix
cd /home/intlc/projects/proxmox
./scripts/fix-blockscout-explorer.sh
```

---

## 📋 Configuration Details

### Container Information

- **VMID**: 5000
- **Hostname**: blockscout-1
- **IP Address**: 192.168.11.140
- **Blockscout Port**: 4000
- **Nginx HTTP Port**: 80
- **Nginx HTTPS Port**: 443

### Nginx Configuration

**Location**: `/etc/nginx/sites-available/blockscout`

- **HTTP (port 80)**: Redirects to HTTPS
- **HTTPS (port 443)**: Proxies to `localhost:4000`
- **SSL Certificate**: `/etc/nginx/ssl/blockscout.crt` (self-signed)
- **Health Check**: `/health` endpoint

### Blockscout Service

- **Service Name**: `blockscout.service`
- **Location**: `/opt/blockscout`
- **Docker Compose**: `/opt/blockscout/docker-compose.yml`
- **RPC URL**: `http://192.168.11.250:8545`

---

## 🌐 Cloudflare Configuration

### DNS Record

**Required DNS Record:**

```
Type: CNAME
Name: explorer
Domain: d-bis.org
Target: <tunnel-id>.cfargotunnel.com
Proxy: 🟠 Proxied (orange cloud) - REQUIRED
TTL: Auto
```

### Tunnel Route

**In Cloudflare Zero Trust Dashboard:**

1. Go to: https://one.dash.cloudflare.com/
2. Navigate to: Zero Trust → Networks → Tunnels
3. Select your tunnel
4. Click 'Configure' → 'Public Hostnames'
5. Add hostname:
   - **Subdomain**: `explorer`
   - **Domain**: `d-bis.org`
   - **Service**: `http://192.168.11.140:80`
   - **Type**: HTTP

**Or configure via script:**

```bash
cd /home/intlc/projects/proxmox
# Ensure .env file exists with CLOUDFLARE_API_TOKEN
./scripts/configure-cloudflare-explorer.sh
```

---

## 🧪 Testing

### 1. Test Blockscout Directly

```bash
# From inside container
pct exec 5000 -- curl http://127.0.0.1:4000/api/v2/status

# From external
curl http://192.168.11.140:4000/api/v2/status
```

**Expected**: JSON response with chain_id and status

### 2. Test Nginx HTTP

```bash
# From inside container
pct exec 5000 -- curl -L http://127.0.0.1/health

# From external
curl -L http://192.168.11.140/health
```

**Expected**: Should redirect to HTTPS, then return JSON

### 3. Test Nginx HTTPS

```bash
# From inside container
pct exec 5000 -- curl -k https://127.0.0.1/health

# From external
curl -k https://192.168.11.140/health
```

**Expected**: JSON response

### 4. Test Public URL (After DNS Propagation)

```bash
curl https://explorer.d-bis.org/health
```

**Expected**: JSON response (may take 1-5 minutes for DNS propagation)

---

## 📊 Verification Checklist

- [ ] Container VMID 5000 exists and is running
- [ ] Blockscout service is active: `systemctl status blockscout`
- [ ] Blockscout responds on port 4000: `curl http://localhost:4000/api/v2/status`
- [ ] Nginx is installed and running: `systemctl status nginx`
- [ ] Nginx configuration is valid: `nginx -t`
- [ ] Port 80 is listening: `ss -tlnp | grep :80`
- [ ] Port 443 is listening: `ss -tlnp | grep :443`
- [ ] Nginx proxies correctly: `curl -k https://localhost/health`
- [ ] Cloudflare DNS record exists (CNAME to tunnel)
- [ ] Cloudflare tunnel route is configured
- [ ] Public URL works: `curl https://explorer.d-bis.org/health`

---

## 🔧 Troubleshooting

### Issue: Container doesn't exist

**Solution**: Deploy container first:
```bash
cd smom-dbis-138-proxmox/scripts/deployment
export VMID_EXPLORER_START=5000
./deploy-explorer.sh
```

### Issue: Blockscout service not running

**Solution**: Start the service:
```bash
pct exec 5000 -- systemctl start blockscout
# Or via docker-compose
pct exec 5000 -- cd /opt/blockscout && docker-compose up -d
```

### Issue: Blockscout not responding on port 4000

**Solution**: 
1. Check service status: `pct exec 5000 -- systemctl status blockscout`
2. Check Docker containers: `pct exec 5000 -- docker ps`
3. Check logs: `pct exec 5000 -- journalctl -u blockscout -n 50`
4. Check Docker logs: `pct exec 5000 -- docker-compose -f /opt/blockscout/docker-compose.yml logs`

### Issue: Nginx not working

**Solution**:
1. Check configuration: `pct exec 5000 -- nginx -t`
2. Check service: `pct exec 5000 -- systemctl status nginx`
3. Check logs: `pct exec 5000 -- tail -f /var/log/nginx/blockscout-error.log`
4. Restart Nginx: `pct exec 5000 -- systemctl restart nginx`

### Issue: HTTP 522 from Cloudflare

**Solution**:
1. Verify Blockscout and Nginx are running (see above)
2. Test direct access: `curl http://192.168.11.140`
3. Verify Cloudflare tunnel is healthy
4. Check tunnel route configuration
5. Verify DNS record is proxied (orange cloud)

### Issue: SSL Certificate Warnings

**Solution**: Replace self-signed certificate with Let's Encrypt:

```bash
pct exec 5000 -- certbot --nginx -d explorer.d-bis.org
```

---

## 📝 Files Created/Modified

### New Scripts

1. `scripts/install-nginx-blockscout.sh` - Nginx installation and configuration
2. `scripts/configure-cloudflare-explorer.sh` - Cloudflare DNS/tunnel setup
3. `scripts/fix-blockscout-explorer.sh` - Comprehensive fix script
4. `scripts/deploy-and-fix-blockscout.sh` - Complete deployment and fix

### Modified Files

1. `smom-dbis-138-proxmox/scripts/deployment/deploy-explorer.sh`
   - Changed default VMID from 140 to 5000
   - Fixed IP subnet from 10.3.1 to 192.168.11

### Documentation

1. `docs/BLOCKSCOUT_EXPLORER_FIX.md` (this file)

---

## 🎯 Next Steps

1. **Deploy Container** (if not exists):
   ```bash
   ssh root@192.168.11.10
   cd /home/intlc/projects/proxmox/smom-dbis-138-proxmox/scripts/deployment
   export VMID_EXPLORER_START=5000
   export PUBLIC_SUBNET=192.168.11
   ./deploy-explorer.sh
   ```

2. **Run Fix Script**:
   ```bash
   cd /home/intlc/projects/proxmox
   ./scripts/fix-blockscout-explorer.sh
   ```

3. **Configure Cloudflare**:
   ```bash
   ./scripts/configure-cloudflare-explorer.sh
   ```
   Or configure manually in Cloudflare dashboard

4. **Verify**:
   ```bash
   curl https://explorer.d-bis.org/health
   ```

5. **Optional: SSL Certificate**:
   Replace self-signed certificate with Let's Encrypt for production use

---

## 📚 Related Documentation

- `docs/BLOCKSCOUT_VERIFICATION_GUIDE.md` - Contract verification guide
- `docs/CHAINID_138_BLOCKSCOUT_INTEGRATION.md` - Integration summary
- `docs/04-configuration/CLOUDFLARE_DNS_SPECIFIC_SERVICES.md` - DNS configuration

---

**Last Updated**: $(date)  
**Status**: ✅ Fix scripts created and ready to use