diff --git a/services/zoraxy.md b/services/zoraxy.md index d8b6788..a2723bf 100644 --- a/services/zoraxy.md +++ b/services/zoraxy.md @@ -1,127 +1,99 @@ -# Zoraxy Reverse Proxy Setup Guide +# Zoraxy Reverse Proxy -> **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\`.** +> Zoraxy is a Go-based reverse proxy + ACME daemon running as a **systemd service** on **LXC 108** (`zoraxy`, 192.168.1.4). Config lives in JSON files at `/opt/zoraxy/conf/proxy/`. Changes take effect after `systemctl restart zoraxy`. +## Current route table -## Overview -Configure reverse proxies for AI service endpoints with automatic SSL certificates. +Audited and fully configured 2026-05-21. All 22 public routes have: +- `EnableAutoHTTPS: true` — Zoraxy requests LE certs for `*.nuclide.systems` +- `EnableWebsocketCustomHeaders: true` — preserves WS upgrade headers through the proxy +- `DisableHopByHopHeaderRemoval: true` — keeps hop-by-hop headers intact for upstream -## Target Services +| Domain | Upstream | Notes | +|--------|----------|-------| +| abs.nuclide.systems | 192.168.1.40:13003 | Absolut (abs) | +| ai.nuclide.systems | 192.168.1.40:14000 | LiteLLM gateway | +| arcane.nuclide.systems | 192.168.1.40:10002 | Arcane Manager | +| chat.nuclide.systems | 192.168.1.40:14001 | LobeHub | +| dev.nuclide.systems | 192.168.1.42:7080 | Coder (CT 111) | +| git.nuclide.systems | 192.168.1.42:3000 | Gitea (CT 111) | +| gotify.nuclide.systems | 192.168.1.40:10003 | Gotify push notifications | +| ha.nuclide.systems | 192.168.1.60:8123 | Home Assistant (VM 100) | +| hoarder.nuclide.systems | 192.168.1.40:17001 | Karakeep bookmarks | +| id.nuclide.systems | 192.168.1.5:11000 | Pocket-ID OIDC (CT 110) | +| immich.nuclide.systems | 192.168.1.40:12000 | Immich photos | +| mcp.nuclide.systems | 192.168.1.40:8080 | MCP gateway | +| memos.nuclide.systems | 192.168.1.40:17000 | Memos notes | +| n8n.nuclide.systems | 192.168.1.40:16000 | n8n workflows | +| nc.nuclide.systems | 192.168.1.41:11000 | Nextcloud AIO (CT 105) | +| ocpp.nuclide.systems | 192.168.1.60:8887 | OCPP charger endpoint (HAOS) | +| s3.nuclide.systems | 192.168.1.40:10004 | Garage S3 (web endpoint) | +| shepard.nuclide.systems | 192.168.1.49:80 | Shepard frontend (CT 101) | +| shepard-api.nuclide.systems | 192.168.1.49:8080 | Shepard API (CT 101) | +| shepard-auth.nuclide.systems | 192.168.1.49:8082 | Shepard auth (CT 101) | +| traccar.nuclide.systems | 192.168.1.40:15000 | Traccar GPS | +| vault.nuclide.systems | 192.168.1.40:11001 | Vaultwarden | -| 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` | +`root.config` — ProxyType=0 internal dashboard fallback (127.0.0.1:5487), no ACME. -## Method A — Zoraxy admin UI (recommended) +## Admin UI -### 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"** +Zoraxy runs with `-noauth=true` — no login required on the LAN. -### Step 3: Add Each Service -Click **"Add New Rule"** and fill in: +## Adding a new route -**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 +### Via admin UI -**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 +1. **Reverse Proxy → Create Proxy Rules → New Proxy Rule** +2. Enter the domain, set the upstream IP:port +3. **TLS → Enable Auto HTTPS** — tick it +4. **Header Rewrite Rules** → enable **Disable Hop-by-Hop Removal** and **WebSocket Custom Headers** +5. Save, allow 1–2 minutes for LE cert issuance -**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 +### Via JSON (preferred for scripted changes) -**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 +Config files live at `/opt/zoraxy/conf/proxy/.config` on CT 108. -### Step 4: Save All Rules -Click **"Save"** at the bottom of the page. +Minimum template for a new public route: -### 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 +```json +{ + "ProxyType": 1, + "RootOrMatchingDomain": "example.nuclide.systems", + "ActiveOrigins": [{"OriginIpOrDomain": "192.168.1.40:PORT", "Weight": 1}], + "TlsOptions": {"EnableAutoHTTPS": true}, + "HeaderRewriteRules": {"DisableHopByHopHeaderRemoval": true}, + "EnableWebsocketCustomHeaders": true, + "AccessFilterUUID": "default" +} ``` -## Verification - -After setup, verify all endpoints: +After editing, restart Zoraxy: ```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/ +ssh root@192.168.1.4 'systemctl restart zoraxy' ``` -Expected: HTTP 200 with SSL certificate. +## Backup / restore -## Troubleshooting +All configs are backed up at `/tmp/zoraxy-backup-2026-05-21/` on CT 108 (22 files from the 2026-05-21 audit). To restore a single route: -### 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 +```bash +ssh root@192.168.1.4 'cp /tmp/zoraxy-backup-2026-05-21/.config /opt/zoraxy/conf/proxy/ && systemctl restart zoraxy' +``` -### 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 +## Decommissioned routes -### Configuration Not Saving -- Check Web UI is logged in (session expiry) -- Try clearing browser cache -- Verify UCI config syntax +`.DECOMMISSIONED-*` files in `/opt/zoraxy/conf/proxy/` are ignored by Zoraxy. Current: +- `daytona.nuclide.systems.config.DECOMMISSIONED-2026-05-20` +- `id.daytona.nuclide.systems.config.DECOMMISSIONED-2026-05-20` -## 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`) +## Auth posture + +No routes have `ForwardAuthURL` set (no Tinyauth/auth middleware). Pocket-ID (`id.nuclide.systems`) is the OIDC IdP; apps that require auth implement it themselves (LobeHub, Coder, Gitea, Nextcloud). Public-facing routes like `ha.nuclide.systems` and `ocpp.nuclide.systems` have no proxy-level auth — upstream apps handle it. + +**Pending**: Tinyauth or similar on unauthenticated-but-sensitive routes (arcane, gotify). Planned for CT 109 deployment.