docs/services/zoraxy.md

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:

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