# 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:

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

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

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

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

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

```bash
# Test nginx configuration
nginx -t

# Reload nginx
systemctl reload nginx
```

### Step 4: Verify

```bash
# 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
   bash scripts/deploy-frontend-to-vmid5000.sh
   ```

2. **Fix Nginx to Serve Custom Frontend**:
   ```bash
   bash scripts/fix-nginx-serve-custom-frontend.sh
   ```

3. **Complete Explorer Fix** (recommended):
   ```bash
   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**:
   ```bash
   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