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:

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

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

```bash
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**:
   ```bash
   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**:
   ```yaml
   environment:
     - PORT=4000
     - HOST=0.0.0.0  # or BINDING_IP=0.0.0.0
   ```

4. **Restart container**:
   ```bash
   pct exec 5000 -- cd /opt/blockscout && docker compose down && docker compose up -d
   ```

#### If Using Systemd:

1. **Edit service file**:
   ```bash
   pct exec 5000 -- systemctl edit blockscout.service
   ```

2. **Add override configuration**:
   ```ini
   [Service]
   Environment="PORT=4000"
   Environment="HOST=0.0.0.0"
   ```

3. **Reload and restart**:
   ```bash
   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**:

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

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

```bash
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**:
```bash
pct exec 5000 -- iptables -L -n | grep 4000
pct exec 5000 -- ufw status | grep 4000
```

**Check port binding**:
```bash
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**:
```bash
# 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**:
```bash
# 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

```bash
# 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](./PORT_4000_INVESTIGATION_REPORT.md) - Investigation findings
- [DIRECT_BLOCKSCOUT_ROUTE_UPDATE.md](./DIRECT_BLOCKSCOUT_ROUTE_UPDATE.md) - Route update documentation
- [APPLY_DIRECT_ROUTE_MANUAL.md](./APPLY_DIRECT_ROUTE_MANUAL.md) - Manual application guide

---

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