reorg: split into infra/ services/ history/ ideas/

2026-05-20 23:25:20 +02:00
parent 04d54ac9b0
commit 99f93b585f
14 changed files with 0 additions and 0 deletions
@@ -0,0 +1,182 @@
+# Zoraxy Reverse Proxy Setup Guide
+
+## Overview
+Configure reverse proxies for AI service endpoints with automatic SSL certificates.
+
+## Target Services
+
+| Service | Domain | Target | Port |
+|---------|--------|--------|------|
+| LiteLLM | `litellm.nuclide.systems` | `192.168.1.40` | `14000` |
+| LobeHub | `chat.nuclide.systems` | `192.168.1.40` | `14001` |
+| MCP Gateway | `mcp.nuclide.systems` | `192.168.1.40` | `8080` |
+| Garage S3 | `s3.nuclide.systems` | `192.168.1.40` | `10004` |
+
+## Option A: Web UI (Easiest - No SSH Required)
+
+### Step 1: Access Zoraxy Panel
+```
+http://192.168.1.4:8000
+```
+
+### Step 2: Navigate to Rewrite Rules
+1. Go to **"Reverse Proxy"** in the left sidebar
+2. Click **"Rewrite Rules"**
+
+### Step 3: Add Each Service
+Click **"Add New Rule"** and fill in:
+
+**For LiteLLM (`litellm.nuclide.systems`):**
+- **Domain:** `litellm.nuclide.systems`
+- **SSL:** `ON`
+- **HTTPS Redirect:** `ON`
+- **HSTS:** `ON`
+- **Target Type:** `Server`
+- **Target:** `192.168.1.40:14000`
+- **Timeout:** `300` seconds
+- **Proxy Time:** `300` seconds
+
+**For LobeHub (`chat.nuclide.systems`):**
+- **Domain:** `chat.nuclide.systems`
+- **SSL:** `ON`
+- **HTTPS Redirect:** `ON`
+- **HSTS:** `ON`
+- **Target Type:** `Server`
+- **Target:** `192.168.1.40:14001`
+- **Timeout:** `300` seconds
+- **Proxy Time:** `300` seconds
+
+**For MCP Gateway (`mcp.nuclide.systems`):**
+- **Domain:** `mcp.nuclide.systems`
+- **SSL:** `ON`
+- **HTTPS Redirect:** `ON`
+- **HSTS:** `ON`
+- **Target Type:** `Server`
+- **Target:** `192.168.1.40:8080`
+- **Timeout:** `300` seconds
+- **Proxy Time:** `300` seconds
+
+**For Garage S3 (`s3.nuclide.systems`):**
+- **Domain:** `s3.nuclide.systems`
+- **SSL:** `ON`
+- **HTTPS Redirect:** `ON`
+- **HSTS:** `ON`
+- **Target Type:** `Server`
+- **Target:** `192.168.1.40:10004`
+- **Timeout:** `300` seconds
+- **Proxy Time:** `300` seconds
+
+### Step 4: Save All Rules
+Click **"Save"** at the bottom of the page.
+
+### Step 5: SSL Certificate Generation
+- Zoraxy automatically initiates Let's Encrypt certificate generation
+- Wait 1-2 minutes for certificates to be issued
+- Visual indicator: Green padlock icon in the UI
+
+## Option B: SSH/UCI (Automated - Requires Root Access)
+
+### Prerequisites
+- SSH access to Zoraxy with root credentials
+- Command-line access to Zoraxy's UCI config system
+
+### Step 1: SSH into Zoraxy
+```bash
+ssh root@192.168.1.4
+```
+
+### Step 2: Configure via UCI
+Run this command directly on Zoraxy:
+
+```bash
+# Apply all rewrite rules
+uci set network.rewrite_litellm.enable='1'
+uci set network.rewrite_litellm.domain='litellm.nuclide.systems'
+uci set network.rewrite_litellm.target_type='0'
+uci set network.rewrite_litellm.target='192.168.1.40:14000'
+uci set network.rewrite_litellm.ssl='1'
+uci set network.rewrite_litellm.hsts='1'
+
+uci set network.rewrite_lobehub.enable='1'
+uci set network.rewrite_lobehub.domain='chat.nuclide.systems'
+uci set network.rewrite_lobehub.target_type='0'
+uci set network.rewrite_lobehub.target='192.168.1.40:14001'
+uci set network.rewrite_lobehub.ssl='1'
+uci set network.rewrite_lobehub.hsts='1'
+
+uci set network.rewrite_mcp.enable='1'
+uci set network.rewrite_mcp.domain='mcp.nuclide.systems'
+uci set network.rewrite_mcp.target_type='0'
+uci set network.rewrite_mcp.target='192.168.1.40:8080'
+uci set network.rewrite_mcp.ssl='1'
+uci set network.rewrite_mcp.hsts='1'
+
+uci set network.rewrite_garage.enable='1'
+uci set network.rewrite_garage.domain='s3.nuclide.systems'
+uci set network.rewrite_garage.target_type='0'
+uci set network.rewrite_garage.target='192.168.1.40:10004'
+uci set network.rewrite_garage.ssl='1'
+uci set network.rewrite_garage.hsts='1'
+
+# Commit and restart
+uci commit network
+/etc/init.d/network restart
+```
+
+### Step 3: Verify
+```bash
+# Check if rewrite rules are loaded
+uci show network.rewrite_*
+
+# Test connectivity
+curl -I http://litellm.nuclide.systems
+```
+
+## Option C: Automated Script (Local)
+
+Run from the control node:
+
+```bash
+# Generate UCI config
+/opt/stacks/scripts/configure_zoraxy_helpers.sh --export-uci
+
+# Or deploy via SSH (requires root@192.168.1.4 SSH access)
+/opt/stacks/scripts/configure_zoraxy_helpers.sh --deploy
+```
+
+## Verification
+
+After setup, verify all endpoints:
+
+```bash
+# Test each service
+curl -I https://litellm.nuclide.systems/health
+curl -I https://chat.nuclide.systems/api/health
+curl -I https://mcp.nuclide.systems/health
+curl -I https://s3.nuclide.systems/
+```
+
+Expected: HTTP 200 with SSL certificate.
+
+## Troubleshooting
+
+### SSL Certificate Issues
+- Wait 2-3 minutes for Let's Encrypt to respond
+- Check domain DNS resolution: `dig litellm.nuclide.systems`
+- Verify firewall allows port 80 validation
+
+### Proxy Connection Failed
+- Check backend service is running: `htop` or `docker ps`
+- Verify internal IP: `192.168.1.40` is reachable from Zoraxy
+- Check target port is correct
+
+### Configuration Not Saving
+- Check Web UI is logged in (session expiry)
+- Try clearing browser cache
+- Verify UCI config syntax
+
+## Notes
+- SSL certificates are **automatic** via Let's Encrypt
+- Zoraxy auto-renews certificates before expiry
+- HSTS is recommended for production use
+- All services use the same target IP (`192.168.1.40`)