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:

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

```bash
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**:
   ```bash
   pct exec 5000 -- systemctl status blockscout.service
   ```

2. **Blockscout is listening on port 4000**:
   ```bash
   pct exec 5000 -- ss -tlnp | grep :4000
   ```

3. **Blockscout is network accessible** (not just localhost):
   ```bash
   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

```bash
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**:
```bash
# 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**:
   ```bash
   # Edit configure-npmplus-domains.js
   # Change port back to 80
   # Run: node configure-npmplus-domains.js
   ```

---

## Related Documentation

- [RPC_ENDPOINTS_MASTER.md](./RPC_ENDPOINTS_MASTER.md) - Master endpoint reference
- [ALL_VMIDS_ENDPOINTS.md](./ALL_VMIDS_ENDPOINTS.md) - All VMID endpoints
- [NPMPLUS_COMPLETE_SETUP_SUMMARY.md](./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.