# Zoraxy Reverse Proxy Setup Guide

> **Zoraxy is a Go-based reverse proxy + ACME daemon, running as a systemd service in LXC 108. It is NOT OpenWRT. Earlier docs referenced \`uci\` commands — those are removed; configuration is via the admin UI or by editing JSON config files in \`/opt/zoraxy/conf/proxy/\` and restarting \`systemctl restart zoraxy\`.**


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

## Method A — Zoraxy admin UI (recommended)

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

## Method B — automation via scripts/zoraxy_sync.py

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