fbda1b4beb
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- ADD_CHAIN138_TO_LEDGER_LIVE: Ledger form done; public code review repo bis-innovations/LedgerLive; init/push commands - CONTRACT_DEPLOYMENT_RUNBOOK: Chain 138 gas price 1 gwei, 36-addr check, TransactionMirror workaround - CONTRACT_*: AddressMapper, MirrorManager deployed 2026-02-12; 36-address on-chain check - NEXT_STEPS_FOR_YOU: Ledger done; steps completable now (no LAN); run-completable-tasks-from-anywhere - MASTER_INDEX, OPERATOR_OPTIONAL, SMART_CONTRACTS_INVENTORY_SIMPLE: updates - LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE: bis-innovations/LedgerLive reference Co-authored-by: Cursor <cursoragent@cursor.com>
327 lines
8.3 KiB
Markdown
327 lines
8.3 KiB
Markdown
# 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
|
|
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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
ssh root@192.168.11.11 "pct exec <NEW_CONTAINER_ID> -- hostname -I"
|
|
```
|
|
|
|
---
|
|
|
|
### Step 5: Test Migration
|
|
|
|
1. **Test Admin UI:**
|
|
```bash
|
|
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
|
|
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:**
|
|
```bash
|
|
ssh root@192.168.11.11 "pct stop 105"
|
|
```
|
|
|
|
2. **Keep for rollback period** (recommended: 7 days)
|
|
|
|
3. **Remove after verification:**
|
|
```bash
|
|
ssh root@192.168.11.11 "pct destroy 105"
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### NPMplus Not Starting
|
|
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
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):**
|
|
```bash
|
|
# 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](https://github.com/ZoeyVid/NPMplus)
|
|
- [Proxmox Helper Scripts](https://github.com/community-scripts/ProxmoxVE)
|
|
- [NPMplus Documentation](https://github.com/ZoeyVid/NPMplus/blob/develop/README.md)
|
|
|
|
---
|
|
|
|
## 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
|