Proxy docs: Proxmox-first design note, multi-environment setup guide

- ProxyManager: full header comment block — Proxmox intended env, non-Proxmox requirements (sshpass + PermitRootLogin), local mode Apache migration steps, cloud/remote server instructions, settings key reference - admin.js: Setup Guide modal rewritten — 4 options (Proxmox LXC, other hypervisors, cloud/remote, local); settings table reference; how-it-works section covering health check, auto config push, and uninstall Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-30 17:50:41 -05:00 · 2026-06-09 10:26:34 +00:00
parent ed552cd5a6
commit dc77c65a3f
2 changed files with 109 additions and 40 deletions
@@ -3,12 +3,54 @@
 * ProxyManager — manages Nginx reverse proxy for NovaCPX hosted accounts.
 * Supports local nginx (on same VM) or remote nginx (separate proxy VM via SSH).
 *
- * Settings keys:
+ * ── INTENDED ENVIRONMENT ────────────────────────────────────────────────────
+ * This proxy feature is designed for Proxmox VE (or similar Linux
+ * hypervisor / LXC / KVM environments) where you run NovaCPX on one VM
+ * and dedicate a lightweight container (Debian/Ubuntu LXC, 512MB RAM,
+ * 1 vCPU) purely to nginx as a reverse proxy.
+ *
+ * Typical stack on Proxmox:
+ *   CT 120  NovaCPX VM  10.48.200.110  — Apache + PHP, panel on :8880–8883
+ *   CT 121  Proxy LXC   10.48.200.112  — nginx only, public ports 80/443
+ *   FortiGate VIPs route 80/443 → 10.48.200.112
+ *
+ * The panel pushes nginx vhost configs to the proxy VM via SSH and can
+ * start/stop/reload nginx remotely — all from Admin → Nginx Proxy.
+ *
+ * ── NON-PROXMOX / BARE-METAL / OTHER HYPERVISORS ────────────────────────────
+ * The feature works on any Linux environment. Requirements:
+ *
+ *   1. A second Linux VM or server accessible by SSH from NovaCPX.
+ *      (AWS EC2, DigitalOcean droplet, VMware VM, Hyper-V, bare-metal — all fine.)
+ *   2. SSH password auth enabled for root (or another sudo user).
+ *   3. The proxy VM must be able to reach NovaCPX's Apache (port 80) via LAN/VPN.
+ *   4. sshpass must be installed on the NovaCPX server: apt-get install -y sshpass
+ *
+ *   Configuration (Admin → Nginx Proxy → Settings):
+ *     Mode:        remote
+ *     Remote host: <proxy VM IP or hostname>
+ *     Remote user: root
+ *     Remote pass: <root SSH password>
+ *     Backend IP:  <this NovaCPX server's IP that Apache listens on>
+ *
+ *   One-time setup: click "Run Setup on Remote VM" — it installs nginx,
+ *   removes the default site, and creates the NovaCPX catch-all.
+ *   After that, add proxy hosts per domain from Admin → Nginx Proxy → Add Host.
+ *
+ * ── LOCAL MODE (nginx on same VM as NovaCPX) ────────────────────────────────
+ * Apache must be moved off port 80/443 first:
+ *   1. Edit /etc/apache2/ports.conf → change Listen 80 to Listen 8090
+ *   2. Restart Apache: systemctl restart apache2
+ *   3. Set proxy_backend_ip = 127.0.0.1 and all upstreams to http://127.0.0.1:8090
+ *   4. Set Mode = local, click Install Nginx Locally
+ *   5. Click Sync Accounts to populate proxy hosts
+ *
+ * ── Settings keys stored in `settings` table ────────────────────────────────
 *   proxy_mode          — 'disabled' | 'local' | 'remote'
 *   proxy_remote_host   — IP/hostname of remote nginx VM
 *   proxy_remote_user   — SSH user (default: root)
 *   proxy_remote_pass   — SSH password
- *   proxy_backend_ip    — IP of NovaCPX Apache server (used when syncing proxy hosts)
+ *   proxy_backend_ip    — IP of NovaCPX Apache (used when syncing proxy hosts)
 */
 class ProxyManager {

@@ -2802,48 +2802,75 @@ window.proxyDeleteHost = (id, domain) => {
 };

 window.proxySetupInstructions = async () => {
-  const scriptUrl = '/api/proxy/setup-script';
  Nova.modal('Nginx Proxy Setup Guide', `
-<div style="max-height:60vh;overflow-y:auto">
-  <h4 style="margin-bottom:0.75rem">Option A — Local (Nginx on this VM)</h4>
-  <p style="color:var(--text-muted);margin-bottom:1rem">Install Nginx alongside Apache on this VM. Nginx listens on ports 80/443 and forwards to Apache. Best for SSL termination and caching.</p>
-  <ol style="color:var(--text-muted);margin-bottom:1.5rem;padding-left:1.2rem;line-height:1.8">
-    <li>Click <strong>Install Nginx Locally</strong> on the main Nginx Proxy page</li>
-    <li>Move Apache to port 8080: edit <code>/etc/apache2/ports.conf</code> → change <code>Listen 80</code> to <code>Listen 8080</code></li>
-    <li>Update upstream in all proxy hosts to <code>http://127.0.0.1:8080</code></li>
-    <li>Click <strong>Sync Accounts</strong> to auto-populate proxy hosts from your hosted accounts</li>
-    <li>Click <strong>Reload Config</strong> to apply changes</li>
-  </ol>
+<div style="max-height:65vh;overflow-y:auto;line-height:1.7">

-  <h4 style="margin-bottom:0.75rem">Option B — Remote Proxy VM (Recommended for production)</h4>
-  <p style="color:var(--text-muted);margin-bottom:1rem">Run a dedicated Nginx proxy VM in front of this NovaCPX VM. Traffic flows: Internet → FortiGate → Nginx Proxy VM → NovaCPX VM (Apache).</p>
-  <ol style="color:var(--text-muted);margin-bottom:1.5rem;padding-left:1.2rem;line-height:1.8">
-    <li>Create a new VM on Proxmox (Ubuntu 22.04, 1 vCPU, 1GB RAM)</li>
-    <li>Run the setup script below on the new VM as root</li>
-    <li>Point FortiGate VIPs to the proxy VM IP (ports 80/443)</li>
-    <li>Set the proxy upstream to this NovaCPX VM IP (<code>http://10.48.200.110:80</code>)</li>
-    <li>Add proxy hosts for each domain from your NovaCPX admin panel</li>
-  </ol>
-
-  <h4 style="margin-bottom:0.75rem">Automated Setup Script</h4>
-  <p style="color:var(--text-muted);margin-bottom:0.75rem">Run this on the target VM (local or remote) as root:</p>
-  <div style="background:var(--bg-secondary);padding:0.75rem;border-radius:6px;font-family:monospace;font-size:0.8rem;margin-bottom:0.75rem">
-    curl -sk https://YOUR_NOVACPX_IP:8882/api/proxy/setup-script | bash
-  </div>
-  <p style="color:var(--text-muted);font-size:0.85rem">Or download and review before running:</p>
-  <div style="background:var(--bg-secondary);padding:0.75rem;border-radius:6px;font-family:monospace;font-size:0.8rem">
-    curl -sk https://YOUR_NOVACPX_IP:8882/api/proxy/setup-script -o proxy-setup.sh<br>
-    cat proxy-setup.sh   # review<br>
-    bash proxy-setup.sh
+  <div style="background:var(--bg-secondary);border-left:3px solid var(--color-primary);padding:0.75rem 1rem;border-radius:0 6px 6px 0;margin-bottom:1.5rem">
+    <strong>Designed for Proxmox (or any Linux hypervisor)</strong><br>
+    <span style="color:var(--text-muted);font-size:0.88rem">
+      Run NovaCPX on one VM and a lightweight Debian LXC as the nginx proxy.
+      The panel pushes configs and controls nginx via SSH.
+      Works equally well on VMware, AWS, DigitalOcean, bare-metal — see Option C below.
+    </span>
  </div>

-  <h4 style="margin-bottom:0.75rem;margin-top:1.5rem">Integration with VirtualHost Manager</h4>
-  <p style="color:var(--text-muted);margin-bottom:0.75rem">When proxy mode is active, NovaCPX automatically:</p>
-  <ul style="color:var(--text-muted);padding-left:1.2rem;line-height:1.8">
-    <li>Creates a proxy host entry for every new account</li>
-    <li>Removes the proxy host when an account is terminated</li>
-    <li>Re-generates Nginx config on every account change</li>
-    <li>Uses account SSL certs automatically if SSL is enabled on the proxy host</li>
+  <h4 style="margin-bottom:0.5rem">Option A — Proxmox LXC (Recommended)</h4>
+  <p style="color:var(--text-muted);margin-bottom:0.75rem">Create a 512MB Debian 12 LXC on the same Proxmox node. Costs almost no resources.</p>
+  <ol style="color:var(--text-muted);margin-bottom:1.5rem;padding-left:1.2rem">
+    <li>In Proxmox: Create CT → Debian 12 → 512MB RAM, 8GB disk, same bridge as NovaCPX VM</li>
+    <li>Boot the LXC, set root password</li>
+    <li>Go to <strong>Settings</strong> → set Mode=Remote, enter the LXC IP, root password, and this VM's IP as Backend IP</li>
+    <li>Click <strong>Run Setup on Remote VM</strong> — watch live progress</li>
+    <li>Point your router/firewall port 80/443 to the LXC IP</li>
+    <li>Click <strong>Sync Accounts</strong> to auto-populate proxy hosts</li>
+  </ol>
+
+  <h4 style="margin-bottom:0.5rem">Option B — Other hypervisors (VMware, Hyper-V, KVM)</h4>
+  <p style="color:var(--text-muted);margin-bottom:0.75rem">Same flow — any Debian/Ubuntu VM reachable by SSH works.</p>
+  <ol style="color:var(--text-muted);margin-bottom:1.5rem;padding-left:1.2rem">
+    <li>Create a Debian/Ubuntu VM (1 vCPU, 512MB RAM)</li>
+    <li>Enable SSH root login: <code>PermitRootLogin yes</code> in <code>/etc/ssh/sshd_config</code></li>
+    <li>Install <code>sshpass</code> on the NovaCPX server: <code>apt-get install -y sshpass</code></li>
+    <li>Follow steps 3–6 from Option A above</li>
+  </ol>
+
+  <h4 style="margin-bottom:0.5rem">Option C — Cloud / Remote Server (AWS, DigitalOcean, etc.)</h4>
+  <p style="color:var(--text-muted);margin-bottom:0.75rem">NovaCPX pushes configs via public SSH. The proxy VM's public IP handles port 80/443; it forwards to NovaCPX over a private network or VPN.</p>
+  <ol style="color:var(--text-muted);margin-bottom:1.5rem;padding-left:1.2rem">
+    <li>Provision a small Debian droplet/instance in the same region or with low latency to NovaCPX</li>
+    <li>Open port 22 (SSH) from NovaCPX's IP only; open 80/443 from anywhere</li>
+    <li>Set Backend IP to NovaCPX's IP reachable from the cloud proxy (use VPN/private IP if possible)</li>
+    <li>In Settings: set Remote Host to the cloud server's public IP or hostname</li>
+    <li>Click Run Setup, then Sync Accounts</li>
+  </ol>
+
+  <h4 style="margin-bottom:0.5rem">Option D — Local nginx on this VM</h4>
+  <p style="color:var(--text-muted);margin-bottom:0.75rem">Not recommended — requires moving Apache off port 80/443 first.</p>
+  <ol style="color:var(--text-muted);margin-bottom:1.5rem;padding-left:1.2rem">
+    <li>Edit <code>/etc/apache2/ports.conf</code> → change <code>Listen 80</code> to <code>Listen 8090</code>, restart Apache</li>
+    <li>Set Settings → Mode = Local, Backend IP = 127.0.0.1</li>
+    <li>Click <strong>Install Nginx Locally</strong></li>
+    <li>Set upstream <code>http://127.0.0.1:8090</code> on all proxy hosts</li>
+    <li>Click Sync Accounts</li>
+  </ol>
+
+  <h4 style="margin-bottom:0.5rem">Settings Reference (Admin → Nginx Proxy → Settings)</h4>
+  <table style="width:100%;font-size:0.83rem;border-collapse:collapse;color:var(--text-muted)">
+    <tr style="border-bottom:1px solid var(--border)"><th style="text-align:left;padding:0.3rem 0.5rem">Field</th><th style="text-align:left;padding:0.3rem 0.5rem">Description</th></tr>
+    <tr><td style="padding:0.3rem 0.5rem"><code>Mode</code></td><td style="padding:0.3rem 0.5rem">disabled / remote / local</td></tr>
+    <tr><td style="padding:0.3rem 0.5rem"><code>Remote Host</code></td><td style="padding:0.3rem 0.5rem">IP or hostname of nginx proxy VM (SSH target)</td></tr>
+    <tr><td style="padding:0.3rem 0.5rem"><code>Remote User</code></td><td style="padding:0.3rem 0.5rem">SSH user on proxy VM (default: root)</td></tr>
+    <tr><td style="padding:0.3rem 0.5rem"><code>Remote Password</code></td><td style="padding:0.3rem 0.5rem">SSH password (stored encrypted in DB)</td></tr>
+    <tr><td style="padding:0.3rem 0.5rem"><code>Backend IP</code></td><td style="padding:0.3rem 0.5rem">IP of this NovaCPX Apache — used in auto-generated proxy upstream URLs</td></tr>
+  </table>
+
+  <h4 style="margin-bottom:0.5rem;margin-top:1.25rem">How it works</h4>
+  <ul style="color:var(--text-muted);padding-left:1.2rem;margin-bottom:0">
+    <li>Each domain gets an nginx vhost config on the proxy VM, proxying to Apache on the backend IP</li>
+    <li>Configs are pushed automatically when accounts are created/terminated or manually via Sync Accounts</li>
+    <li>The panel starts/stops/reloads nginx on the proxy VM over SSH</li>
+    <li>Every 5 minutes the health check verifies nginx is running and restarts it if not</li>
+    <li>Use <strong>Uninstall</strong> to remove proxy configs or wipe nginx from the remote VM entirely</li>
  </ul>
 </div>
  `, null, { cancelLabel: 'Close', showConfirm: false });