proxmox/docs/04-configuration/NPMPLUS_MIGRATION_GUIDE.md

NPMplus Migration Guide

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

---

Date: 2026-01-09
Status: Migration Script Ready
Source: Nginx Proxy Manager (VMID 105)
Target: NPMplus (New Container)

---

Overview

This guide documents the migration from standard Nginx Proxy Manager to NPMplus, an enhanced fork with additional features:

• ✅ HTTP/3 (QUIC) support
• ✅ CrowdSec IPS integration
• ✅ GoAccess for real-time log analysis
• ✅ ModSecurity with Core Rule Set
• ✅ OCSP stapling/must-staple
• ✅ TLS 1.2/1.3 only
• ✅ Faster certificate creation
• ✅ Admin UI on port 81 over HTTPS

---

Pre-Migration Checklist

• Backup current NPM database and configurations
• Document all 19 domain configurations
• Verify DNS records point to correct IP
• Ensure port 80/443 are available
• Have ACME email ready: nsatoshi2007@hotmail.com

---

Migration Steps

Step 1: Run Migration Script

The automated migration script handles:

1. Backing up current NPM configuration
2. Installing NPMplus in a new container
3. Migrating all 19 domain configurations
4. Requesting SSL certificates

bash scripts/nginx-proxy-manager/migrate-to-npmplus.sh

What the script does:

• Creates backup in /tmp/npm-migration-YYYYMMDD_HHMMSS/
• Installs NPMplus using Proxmox community script
• Waits for NPMplus to be ready (1-2 minutes)
• Retrieves admin password from container logs
• Configures all 19 domains via API
• Requests Let's Encrypt certificates

---

Step 2: Manual Installation (Alternative)

If you prefer manual installation:

# On Proxmox host
bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/npmplus.sh)"

During installation:

• Choose container resources (default: 1 vCPU, 512 MB RAM, 3 GB disk)
• Enter timezone (e.g., America/New_York)
• Enter ACME email: nsatoshi2007@hotmail.com

After installation:

• Access URL: https://<container-IP>:81
• Default admin email: admin@example.org
• Get password: pct exec <CTID> -- cat /opt/.npm_pwd or docker logs npmplus | grep -i password

---

Step 3: Configure Domains

If using manual installation, configure all 19 domains:

sankofa.nexus Zone (5 domains)

• sankofa.nexus → http://192.168.11.140:80
• www.sankofa.nexus → http://192.168.11.140:80
• phoenix.sankofa.nexus → http://192.168.11.140:80
• www.phoenix.sankofa.nexus → http://192.168.11.140:80
• the-order.sankofa.nexus → http://192.168.11.140:80

d-bis.org Zone (9 domains)

• explorer.d-bis.org → http://192.168.11.140:80
• rpc-http-pub.d-bis.org → https://192.168.11.252:443 (WebSocket: ✅)
• rpc-ws-pub.d-bis.org → https://192.168.11.252:443 (WebSocket: ✅)
• rpc-http-prv.d-bis.org → https://192.168.11.251:443 (WebSocket: ✅)
• rpc-ws-prv.d-bis.org → https://192.168.11.251:443 (WebSocket: ✅)
• dbis-admin.d-bis.org → http://192.168.11.130:80
• dbis-api.d-bis.org → http://192.168.11.155:3000
• dbis-api-2.d-bis.org → http://192.168.11.156:3000
• secure.d-bis.org → http://192.168.11.130:80

mim4u.org Zone (4 domains)

• mim4u.org → http://192.168.11.36:80
• www.mim4u.org → http://192.168.11.36:80
• secure.mim4u.org → http://192.168.11.36:80
• training.mim4u.org → http://192.168.11.36:80

defi-oracle.io Zone (1 domain)

• rpc.public-0138.defi-oracle.io → https://192.168.11.252:443 (WebSocket: ✅)

For each domain:

1. Proxy Hosts → Add Proxy Host
2. Details Tab:
   • Domain Names: Enter domain
   • Scheme: http or https (based on target)
   • Forward Hostname/IP: Enter target IP
   • Forward Port: Enter target port
   • Block Common Exploits: ✅ Enable
   • Websockets Support: ✅ Enable (for RPC domains)
3. SSL Tab:
   • Request a new SSL Certificate
   • Email: nsatoshi2007@hotmail.com
   • I Agree to Terms: ✅ Check
   • Force SSL: ✅ Enable
   • HTTP/2 Support: ✅ Enable
   • HSTS Enabled: ✅ Enable
4. Click Save

---

Step 4: Update Network Configuration

After NPMplus is configured, update network settings:

Update UDM Pro Port Forwarding

1. Log into UDM Pro
2. Go to Settings → Networks → Port Forwarding
3. Update rules to point to new NPMplus container IP:
   • HTTP (Port 80): 76.53.10.36:80 → <new-npmplus-ip>:80
   • HTTPS (Port 443): 76.53.10.36:443 → <new-npmplus-ip>:443

Verify Container IP

ssh root@192.168.11.11 "pct exec <NEW_CONTAINER_ID> -- hostname -I"

---

Step 5: Test Migration

1. Test Admin UI:

   curl -k https://<npmplus-ip>:81
   

2. Test Domain Access:

   • Visit each domain in browser
   • Verify SSL certificates are valid
   • Check HTTPS redirects work

3. Test SSL Certificates:

   bash scripts/check-east-west-ssl-status.sh
   

4. Verify All Domains:

   • Check all 19 domains are accessible
   • Verify SSL certificates are issued
   • Test WebSocket connections for RPC domains

---

Step 6: Update Scripts and Documentation

After successful migration, update:

1. Update container ID in scripts:

   • scripts/nginx-proxy-manager/configure-domains-pct-exec.sh
   • scripts/nginx-proxy-manager/configure-ssl-api.js
   • scripts/nginx-proxy-manager/reset-npm-password.sh
   • Any other scripts referencing VMID 105

2. Update documentation:

   • Update IP addresses in docs
   • Update container references
   • Document new NPMplus features

3. Update environment variables:

   • Update .env file with new NPM URL
   • Update any CI/CD configurations

---

Step 7: Decommission Old NPM (Optional)

After verifying everything works:

1. Stop old container:

   ssh root@192.168.11.11 "pct stop 105"
   

2. Keep for rollback period (recommended: 7 days)

3. Remove after verification:

   ssh root@192.168.11.11 "pct destroy 105"
   

---

Troubleshooting

NPMplus Not Starting

# Check container status
ssh root@192.168.11.11 "pct status <CONTAINER_ID>"

# Check Docker logs
ssh root@192.168.11.11 "pct exec <CONTAINER_ID> -- docker logs npmplus"

# Check Docker Compose
ssh root@192.168.11.11 "pct exec <CONTAINER_ID> -- docker compose ps"

Cannot Access Admin UI

1. Verify container is running
2. Check firewall rules
3. Verify port 81 is accessible
4. Try accessing via container IP directly

SSL Certificates Not Issuing

1. Verify DNS records point to correct IP
2. Check Let's Encrypt rate limits
3. Verify ACME email is correct
4. Check NPMplus logs: docker logs npmplus

Migration Script Fails

1. Check backup directory for exported configs
2. Manually configure domains via web UI
3. Use API script: scripts/nginx-proxy-manager/configure-ssl-api.js

---

Rollback Plan

If migration fails:

1. Restore old NPM:

   ssh root@192.168.11.11 "pct start 105"
   

2. Update port forwarding back to old IP:

   • UDM Pro → Port Forwarding → Update to 192.168.11.26

3. Restore database (if needed):

   # From backup directory
   ssh root@192.168.11.11 "pct exec 105 -- bash -c 'sqlite3 /data/database.sqlite < /tmp/restore.sql'"
   

---

NPMplus Features

HTTP/3 (QUIC)

• Enabled by default in NPMplus
• Faster connection establishment
• Better performance on high-latency networks

CrowdSec IPS

• Integrated Intrusion Prevention System
• Automatic threat detection
• Community-driven rules

GoAccess

• Real-time log analysis
• Access via web interface
• Detailed traffic statistics

ModSecurity

• Web Application Firewall
• Core Rule Set included
• Protection against common attacks

---

References

• NPMplus GitHub
• Proxmox Helper Scripts
• NPMplus Documentation

---

Migration Checklist

• Backup current NPM
• Install NPMplus
• Configure all 19 domains
• Request SSL certificates
• Update UDM Pro port forwarding
• Test all domains
• Verify SSL certificates
• Update scripts and documentation
• Test WebSocket connections
• Monitor for 24-48 hours
• Decommission old NPM (optional)

---

Last Updated: 2026-01-09
Migration Status: Ready to Execute