# 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