docs/services/zoraxy.md

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

ssh root@192.168.1.4

Step 2: Configure via UCI

Run this command directly on Zoraxy:

# 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

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

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

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