proxmox/docs/04-configuration/DIRECT_BLOCKSCOUT_ROUTE_UPDATE.md

Direct Blockscout Route Configuration - Complete Update

Last Updated: 2026-01-31
Document Version: 1.0
Status: Active Documentation

---

Date: 2026-01-18
Status: ✅ Configuration Files Updated
Action Required: Apply NPMplus Configuration Update

---

Summary

All configuration files have been updated to use a direct route to Blockscout, bypassing nginx on VMID 5000:

• Old Route: NPMplus → 192.168.11.140:80 (nginx) → 127.0.0.1:4000 (Blockscout)
• New Route: NPMplus → 192.168.11.140:4000 (Blockscout directly)

Benefits

✅ Removes nginx proxy layer (one less hop)
✅ Reduces latency
✅ Fewer points of failure
✅ Simpler architecture
✅ Should fix 502 Bad Gateway errors

---

Files Updated

✅ Configuration Scripts

1. scripts/nginx-proxy-manager/configure-npmplus-domains.js

   • Updated: explorer.d-bis.org → http://192.168.11.140:4000

2. scripts/nginx-proxy-manager/configure-ssl-all-domains.js

   • Updated: explorer.d-bis.org → http://192.168.11.140:4000

3. scripts/nginx-proxy-manager/configure-ssl-api.js

   • Updated: explorer.d-bis.org → http://192.168.11.140:4000

✅ Documentation

1. docs/04-configuration/RPC_ENDPOINTS_MASTER.md

   • Updated port from 80 to 4000
   • Added note: "Direct Route - bypasses nginx"

2. docs/04-configuration/ALL_VMIDS_ENDPOINTS.md

   • Updated port from 80 to 4000
   • Added note: "Direct Route"

✅ New Scripts Created

1. scripts/configure-direct-blockscout-route.sh

   • Diagnostic script to check Blockscout configuration
   • Verifies network accessibility
   • Creates update script if ready

2. scripts/apply-direct-blockscout-route.sh

   • Main script to apply the direct route configuration
   • Runs NPMplus update automatically

3. scripts/nginx-proxy-manager/update-explorer-direct-route.js

   • Automated NPMplus configuration update
   • Uses Playwright to update proxy host settings

4. scripts/diagnose-explorer-502-error.sh

   • Comprehensive diagnostic tool for 502 errors
   • Checks all components of the routing chain

---

How to Apply Changes

Option 1: Automated Update (Recommended)

Run the automated update script from a machine that can access NPMplus:

cd /home/intlc/projects/proxmox
./scripts/apply-direct-blockscout-route.sh

This will:

1. Check dependencies
2. Log into NPMplus
3. Update explorer.d-bis.org proxy host
4. Change port from 80 to 4000
5. Save changes

Option 2: Manual Update

If automated update doesn't work, update manually:

1. Log into NPMplus:

   • URL: https://192.168.0.166:81
   • Email: nsatoshi2007@hotmail.com
   • Password: (from .env file)

2. Navigate to Proxy Hosts:

   • Click on "Proxy Hosts" in the menu
   • Find explorer.d-bis.org

3. Update Configuration:

   • Forward Host: 192.168.11.140
   • Forward Port: 4000 (change from 80)
   • Forward Scheme: http
   • WebSocket Support: Unchecked (not needed)

4. Save Changes:

   • Click "Save"
   • Wait 10-30 seconds for NPMplus to reload

Option 3: Re-run Full Configuration

If you want to reconfigure all domains with the new settings:

cd /home/intlc/projects/proxmox/scripts/nginx-proxy-manager
node configure-npmplus-domains.js

This will update all domains, including the direct route for explorer.

---

Prerequisites

Before applying the direct route, ensure:

1. Blockscout is running:

   pct exec 5000 -- systemctl status blockscout.service
   

2. Blockscout is listening on port 4000:

   pct exec 5000 -- ss -tlnp | grep :4000
   

3. Blockscout is network accessible (not just localhost):

   curl -I http://192.168.11.140:4000/api/v2/stats
   

If Blockscout is only listening on 127.0.0.1:4000, you need to configure it to listen on 0.0.0.0:4000 first.

---

Verification

After applying changes, verify the direct route works:

1. Test API Endpoint

curl -I https://explorer.d-bis.org/api/v2/stats

Should return HTTP 200 (not 502).

2. Test from Browser

Open browser console and check:

• No 502 errors
• API calls succeed
• Blocks load correctly

3. Check NPMplus Logs

In NPMplus, check the proxy host logs to see if requests are reaching Blockscout.

---

Troubleshooting

Issue: Still Getting 502 Errors

Possible Causes:

1. Blockscout service not running
2. Blockscout not listening on port 4000
3. Blockscout only listening on localhost (127.0.0.1)
4. Firewall blocking port 4000

Solutions:

# Check Blockscout status
pct exec 5000 -- systemctl status blockscout.service

# Check port listening
pct exec 5000 -- ss -tlnp | grep :4000

# Test direct connection
curl -I http://192.168.11.140:4000/api/v2/stats

# Check firewall
pct exec 5000 -- iptables -L -n | grep 4000

Issue: NPMplus Update Script Fails

Solutions:

1. Check NPMplus URL is correct in .env file
2. Verify credentials are correct
3. Try manual update instead
4. Check NPMplus is accessible from your machine

Issue: Blockscout Not Network Accessible

If Blockscout is only listening on localhost, you need to configure it:

For Docker containers:

• Check docker-compose.yml for port binding
• Ensure port is bound to 0.0.0.0:4000, not 127.0.0.1:4000

For systemd services:

• Check service file: pct exec 5000 -- systemctl cat blockscout.service
• Update environment variables to bind to 0.0.0.0

---

Rollback

If you need to rollback to the old route (via nginx port 80):

1. In NPMplus:

   • Update explorer.d-bis.org Forward Port back to 80
   • Save changes

2. Or run:

   # Edit configure-npmplus-domains.js
   # Change port back to 80
   # Run: node configure-npmplus-domains.js
   

---

Related Documentation

• RPC_ENDPOINTS_MASTER.md - Master endpoint reference
• ALL_VMIDS_ENDPOINTS.md - All VMID endpoints
• NPMPLUS_COMPLETE_SETUP_SUMMARY.md - NPMplus setup

---

Change Log

2026-01-18

• ✅ Created direct route configuration
• ✅ Updated all configuration scripts
• ✅ Updated documentation
• ✅ Created diagnostic and update scripts
• ⏳ Pending: Apply NPMplus configuration update

---

Next Step: Run ./scripts/apply-direct-blockscout-route.sh to apply the changes to NPMplus.