264 lines
6.7 KiB
Markdown
264 lines
6.7 KiB
Markdown
# 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
|