proxmox/docs/04-configuration/PORT_4000_IMPLEMENTATION_GUIDE.md

Port 4000 Implementation Guide - Blockscout Direct Route

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

---

Date: 2026-01-18
Status: ⚠️ Implementation Required
VMID: 5000 (192.168.11.140)

---

Current Situation

✅ Configuration files: All updated to reference port 4000
❌ Blockscout service: Not running or not accessible on port 4000
❌ Port 4000: Not listening
⚠️ Access: Requires Proxmox host access to fix

---

Implementation Steps

Step 1: Access Proxmox Host

From the Proxmox host (192.168.11.11), run the diagnostic:

cd /home/intlc/projects/proxmox
./scripts/diagnose-blockscout-port-4000.sh

Step 2: Check Blockscout Configuration

Determine how Blockscout is running:

Option A: Check Docker Containers

pct exec 5000 -- docker ps -a | grep blockscout

If using Docker, check:

• docker-compose.yml location: /opt/blockscout/ or /root/blockscout/
• Port binding should be: 4000:4000 (not 127.0.0.1:4000:4000)

Option B: Check Systemd Service

pct exec 5000 -- systemctl status blockscout.service
pct exec 5000 -- systemctl cat blockscout.service

Step 3: Fix Port Binding

If Using Docker:

1. Find docker-compose.yml:

   pct exec 5000 -- find /opt /root -name docker-compose.yml 2>/dev/null | grep blockscout
   

2. Update port binding:

   • Change from: "127.0.0.1:4000:4000"
   • Change to: "4000:4000" or "0.0.0.0:4000:4000"

3. Update environment variables:

   environment:
     - PORT=4000
     - HOST=0.0.0.0  # or BINDING_IP=0.0.0.0
   

4. Restart container:

   pct exec 5000 -- cd /opt/blockscout && docker compose down && docker compose up -d
   

If Using Systemd:

1. Edit service file:

   pct exec 5000 -- systemctl edit blockscout.service
   

2. Add override configuration:

   [Service]
   Environment="PORT=4000"
   Environment="HOST=0.0.0.0"
   

3. Reload and restart:

   pct exec 5000 -- systemctl daemon-reload
   pct exec 5000 -- systemctl restart blockscout.service
   

Step 4: Verify Port 4000 Accessibility

From Proxmox host or any machine on the network:

# Test network accessibility
curl -I http://192.168.11.140:4000/api/v2/stats

# Should return HTTP 200

If successful, you should see:

HTTP/1.1 200 OK

Step 5: Update NPMplus Configuration

Only after Step 4 succeeds, update NPMplus:

Option A: Automated Update

cd /home/intlc/projects/proxmox
./scripts/update-npmplus-explorer-port-4000.sh

Option B: Manual Update via Web UI

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 "Proxy Hosts" in menu
   • Find explorer.d-bis.org

3. Update Configuration:

   • Forward Host: 192.168.11.140 (should already be correct)
   • Forward Port: Change from 80 to 4000 ⚠️
   • Forward Scheme: http
   • WebSocket Support: Unchecked

4. Save Changes:

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

Step 6: Verify Public Domain

Test the public domain:

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

Expected: HTTP 200 (not 502)

---

Troubleshooting

Issue: Port 4000 Still Not Accessible After Fix

Check firewall:

pct exec 5000 -- iptables -L -n | grep 4000
pct exec 5000 -- ufw status | grep 4000

Check port binding:

pct exec 5000 -- ss -tlnp | grep :4000
# Should show: 0.0.0.0:4000 (not 127.0.0.1:4000)

Issue: Blockscout Service Won't Start

Check logs:

# For systemd
pct exec 5000 -- journalctl -u blockscout.service -n 50

# For Docker
pct exec 5000 -- docker logs <container-name>

Issue: Still Getting 502 After NPMplus Update

Verify Blockscout is accessible:

# From Proxmox host
curl -I http://192.168.11.140:4000/api/v2/stats

Check NPMplus logs:

• Log into NPMplus UI
• Check proxy host logs for explorer.d-bis.org

---

Quick Reference Commands

# Run full diagnostic
./scripts/diagnose-blockscout-port-4000.sh

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

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

# Test localhost
pct exec 5000 -- curl -I http://127.0.0.1:4000/api/v2/stats

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

# Test public domain (after NPMplus update)
curl -I https://explorer.d-bis.org/api/v2/stats

---

Implementation Checklist

• Access Proxmox host (192.168.11.11)
• Run diagnostic script
• Determine Blockscout configuration (Docker or systemd)
• Fix port binding to 0.0.0.0:4000
• Restart Blockscout service
• Verify port 4000 is accessible (curl -I http://192.168.11.140:4000/api/v2/stats)
• Update NPMplus configuration (port 80 → 4000)
• Verify public domain works (curl -I https://explorer.d-bis.org/api/v2/stats)

---

Related Documentation

• PORT_4000_INVESTIGATION_REPORT.md - Investigation findings
• DIRECT_BLOCKSCOUT_ROUTE_UPDATE.md - Route update documentation
• APPLY_DIRECT_ROUTE_MANUAL.md - Manual application guide

---

Last Updated: 2026-01-18
Status: Ready for implementation (requires Proxmox host access)