explorer-monorepo/EXPLORER_FIX_INSTRUCTIONS.md

Explorer Fix Instructions

Issue: explorer.d-bis.org is not accessible (returns HTTP 000 / 502 error)

Root Cause: The explorer frontend is not deployed and/or nginx is not properly configured

Solution: Deploy the static HTML frontend to /var/www/html/ on VMID 5000 and ensure nginx is configured correctly

---

Quick Fix (Recommended)

Option 1: Run from Proxmox Host

From the Proxmox host, run:

cd /home/intlc/projects/proxmox/explorer-monorepo
bash scripts/fix-explorer-complete.sh

This script will:

1. ✅ Deploy the static HTML frontend to /var/www/html/index.html on VMID 5000
2. ✅ Configure nginx to serve the static frontend
3. ✅ Proxy /api/ requests to Blockscout (port 4000)
4. ✅ Ensure nginx is running
5. ✅ Test the deployment

Option 2: Run from Inside VMID 5000

If you have SSH access to VMID 5000:

# SSH into VMID 5000
ssh root@192.168.11.140

# Run the fix script
cd /home/intlc/projects/proxmox/explorer-monorepo
bash scripts/fix-explorer-complete.sh

The script automatically detects if it's running inside the container and adjusts accordingly.

---

Manual Fix Steps

If the script doesn't work, follow these manual steps:

Step 1: Deploy Frontend

# From Proxmox host
pct push 5000 /home/intlc/projects/proxmox/explorer-monorepo/frontend/public/index.html /var/www/html/index.html
pct exec 5000 -- chown www-data:www-data /var/www/html/index.html

Or from inside VMID 5000:

cp /home/intlc/projects/proxmox/explorer-monorepo/frontend/public/index.html /var/www/html/index.html
chown www-data:www-data /var/www/html/index.html

Step 2: Configure Nginx

Update /etc/nginx/sites-available/blockscout to serve the static frontend:

# HTTPS server
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name explorer.d-bis.org 192.168.11.140;

    # SSL configuration
    ssl_certificate /etc/letsencrypt/live/explorer.d-bis.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/explorer.d-bis.org/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    # Serve custom frontend for root path
    location = / {
        root /var/www/html;
        try_files /index.html =404;
    }

    # Serve static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        root /var/www/html;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # API endpoint - proxy to Blockscout
    location /api/ {
        proxy_pass http://127.0.0.1:4000;
        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;
        add_header Access-Control-Allow-Origin *;
    }
}

Step 3: Test and Reload Nginx

# Test nginx configuration
nginx -t

# Reload nginx
systemctl reload nginx

Step 4: Verify

# Check if frontend file exists
ls -la /var/www/html/index.html

# Test HTTP endpoint
curl -I http://localhost/

# Test external endpoint
curl -I https://explorer.d-bis.org

---

Alternative: Use Existing Deploy Scripts

The repository contains several deployment scripts:

1. Deploy Frontend to VMID 5000:

   bash scripts/deploy-frontend-to-vmid5000.sh
   

2. Fix Nginx to Serve Custom Frontend:

   bash scripts/fix-nginx-serve-custom-frontend.sh
   

3. Complete Explorer Fix (recommended):

   bash scripts/fix-explorer-complete.sh
   

---

Troubleshooting

Issue: Frontend not loading

Check:

1. Is /var/www/html/index.html present?
2. Are file permissions correct? (www-data:www-data)
3. Is nginx configured to serve from /var/www/html?
4. Check nginx error logs: tail -f /var/log/nginx/error.log

Issue: API endpoints not working

Check:

1. Is Blockscout running on port 4000? (curl http://127.0.0.1:4000/api/v2/stats)
2. Is nginx proxying /api/ correctly?
3. Check Blockscout logs: journalctl -u blockscout.service -n 50

Issue: 502 Bad Gateway

Check:

1. Is Blockscout service running? (systemctl status blockscout)
2. Is Blockscout listening on port 4000? (ss -tlnp | grep 4000)
3. Can nginx reach Blockscout? (curl http://127.0.0.1:4000/api/v2/stats from inside VMID 5000)

Issue: Cloudflare Error 530

Check:

1. Is Cloudflare tunnel running? (systemctl status cloudflared)
2. Is the tunnel configured correctly?
3. Check Cloudflare tunnel logs: journalctl -u cloudflared -n 50

---

Architecture Overview

The explorer consists of:

1. Static HTML Frontend (/var/www/html/index.html)

   • Served by nginx
   • Uses Blockscout API for blockchain data
   • Falls back to direct RPC calls if API unavailable

2. Blockscout API (port 4000)

   • Provides blockchain explorer API endpoints
   • Proxied by nginx at /api/

3. Nginx (ports 80, 443)

   • Serves static frontend
   • Proxies API requests to Blockscout
   • Handles SSL termination

4. Cloudflare Tunnel (optional)

   • Provides public access to the explorer
   • Handles SSL termination

---

Verification Checklist

After running the fix:

• /var/www/html/index.html exists
• File permissions are www-data:www-data
• Nginx configuration is valid (nginx -t)
• Nginx is running (systemctl status nginx)
• HTTP endpoint responds (curl -I http://localhost/)
• HTTPS endpoint responds (curl -I https://explorer.d-bis.org)
• API endpoints work (curl https://explorer.d-bis.org/api/v2/stats)
• Frontend loads in browser

---

Next Steps

After fixing the explorer:

1. Monitor logs:

   tail -f /var/log/nginx/blockscout-access.log
   tail -f /var/log/nginx/blockscout-error.log
   

2. Set up monitoring:

   • Monitor nginx status
   • Monitor Blockscout service status
   • Monitor Cloudflare tunnel status

3. Consider automation:

   • Set up systemd service for auto-restart
   • Set up monitoring alerts
   • Set up automated backups

---

Additional Resources

• Explorer Frontend: /home/intlc/projects/proxmox/explorer-monorepo/frontend/public/index.html
• Nginx Config: /etc/nginx/sites-available/blockscout
• Deployment Scripts: /home/intlc/projects/proxmox/explorer-monorepo/scripts/
• Documentation: /home/intlc/projects/proxmox/explorer-monorepo/docs/

---

Last Updated: 2026-01-19
Status: ✅ Fix script ready, awaiting deployment to VMID 5000