fkrebs/docs
1
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite zoraxy.md — full route table, audit status, config guide

Browse Source 
Replaces outdated setup-only guide with current state:
- Full 22-route table with upstream IPs (audited 2026-05-21)
- All routes confirmed ACME+WS+Hop enabled
- JSON template for adding new routes
- Auth posture section with open items (Tinyauth pending CT 109)
- Backup/restore instructions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Florian Krebs
2026-05-21 09:52:25 +02:00
parent 52db8ce9ed
commit 0def5c0be9
1 changed files with 70 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files
services/zoraxy.md
+70 -98
View File
@@ -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 Audited and fully configured 2026-05-21. All 22 public routes have:
Configure reverse proxies for AI service endpoints with automatic SSL certificates. - `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 | `root.config` — ProxyType=0 internal dashboard fallback (127.0.0.1:5487), no ACME.
|---------|--------|--------|------|
| 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) ## Admin UI
### Step 1: Access Zoraxy Panel
``` ```
http://192.168.1.4:8000 http://192.168.1.4:8000
``` ```
### Step 2: Navigate to Rewrite Rules Zoraxy runs with `-noauth=true` — no login required on the LAN.
1. Go to **"Reverse Proxy"** in the left sidebar
2. Click **"Rewrite Rules"**
### Step 3: Add Each Service ## Adding a new route
Click **"Add New Rule"** and fill in:
**For LiteLLM (`litellm.nuclide.systems`):** ### Via admin UI
- **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`):** 1. **Reverse Proxy → Create Proxy Rules → New Proxy Rule**
- **Domain:** `chat.nuclide.systems` 2. Enter the domain, set the upstream IP:port
- **SSL:** `ON` 3. **TLS → Enable Auto HTTPS** — tick it
- **HTTPS Redirect:** `ON` 4. **Header Rewrite Rules** → enable **Disable Hop-by-Hop Removal** and **WebSocket Custom Headers**
- **HSTS:** `ON` 5. Save, allow 1–2 minutes for LE cert issuance
- **Target Type:** `Server`
- **Target:** `192.168.1.40:14001`
- **Timeout:** `300` seconds
- **Proxy Time:** `300` seconds
**For MCP Gateway (`mcp.nuclide.systems`):** ### Via JSON (preferred for scripted changes)
- **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`):** Config files live at `/opt/zoraxy/conf/proxy/<domain>.config` on CT 108.
- **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 Minimum template for a new public route:
Click **"Save"** at the bottom of the page.
### Step 5: SSL Certificate Generation ```json
- Zoraxy automatically initiates Let's Encrypt certificate generation {
- Wait 1-2 minutes for certificates to be issued "ProxyType": 1,
- Visual indicator: Green padlock icon in the UI "RootOrMatchingDomain": "example.nuclide.systems",
"ActiveOrigins": [{"OriginIpOrDomain": "192.168.1.40:PORT", "Weight": 1}],
## Method B — automation via scripts/zoraxy_sync.py "TlsOptions": {"EnableAutoHTTPS": true},
"HeaderRewriteRules": {"DisableHopByHopHeaderRemoval": true},
Run from the control node: "EnableWebsocketCustomHeaders": true,
"AccessFilterUUID": "default"
```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 editing, restart Zoraxy:
After setup, verify all endpoints:
```bash ```bash
# Test each service ssh root@192.168.1.4 'systemctl restart zoraxy'
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. ## 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 ```bash
- Wait 2-3 minutes for Let's Encrypt to respond ssh root@192.168.1.4 'cp /tmp/zoraxy-backup-2026-05-21/<domain>.config /opt/zoraxy/conf/proxy/ && systemctl restart zoraxy'
- Check domain DNS resolution: `dig litellm.nuclide.systems` ```
- Verify firewall allows port 80 validation
### Proxy Connection Failed ## Decommissioned routes
- 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 `.DECOMMISSIONED-*` files in `/opt/zoraxy/conf/proxy/` are ignored by Zoraxy. Current:
- Check Web UI is logged in (session expiry) - `daytona.nuclide.systems.config.DECOMMISSIONED-2026-05-20`
- Try clearing browser cache - `id.daytona.nuclide.systems.config.DECOMMISSIONED-2026-05-20`
- Verify UCI config syntax
## Notes ## Auth posture
- SSL certificates are **automatic** via Let's Encrypt
- Zoraxy auto-renews certificates before expiry 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.
- HSTS is recommended for production use
- All services use the same target IP (`192.168.1.40`) **Pending**: Tinyauth or similar on unauthenticated-but-sensitive routes (arcane, gotify). Planned for CT 109 deployment.