# 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`)