> **STATUS: ABANDONED 2026-05-16 — Zoraxy is the production reverse proxy. Kept for design-decision history. See services/zoraxy.md for current setup.**

---

# Recommended: Traefik Proxy Replacement

## Why Traefik over Zoraxy?

| Feature | Zoraxy | Traefik |
|---------|--------|---------|
| **API** | ❌ No public API | ✅ Full REST API |
| **SSL** | 💬 Manual (Zoraxy Web UI) | 🔥 Auto-Let's Encrypt |
| **Dynamic** | ⚠️ Manual config reload | ✅ Hot-reload configs |
| **File watching** | ❌ | ✅ Auto-detect changes |
| **Docker integration** | ⚠️ Manual | ✅ Native labels |
| **API endpoints** | 403 Forbidden | ✅ JSON API everywhere |

## Migration Path

### Current setup:
```
Zoraxy (192.168.1.4:8000) → Reverse Proxy Rules (Manual Web UI)
- litellm.nuclide.systems → 192.168.1.40:14000
- chat.nuclide.systems → 192.168.1.40:14001  
- mcp.nuclide.systems → 192.168.1.40:8080
- s3.nuclide.systems → Garage:10004
```

### New setup with Traefik:
```
Traefik (public SSL) → Dynamic Router (labels/consul)
- All services auto-discovered via Docker labels
- SSL certificates auto-provisioned
- No manual Zoraxy configuration needed
```

## Installation

### Step 1: Install Traefik

```bash
# Create Traefik directory
mkdir -p /opt/stacks/proxy/traefik/{conf,dynamic}

# Create docker-compose.yml
cat > /opt/stacks/proxy/traefik/docker-compose.yml << 'EOF'
version: "3.8"

services:
  traefik:
    image: traefik:v3.2
    container_name: traefik
    restart: always
    security_opt:
      - no-new-privileges=true
    network_mode: host
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /opt/stacks/proxy/traefik/conf:/etc/traefik
      - /opt/stacks/proxy/traefik/dynamic:/etc/traefik/dynamic
      - /opt/stacks/proxy/traefik/letsencrypt:/etc/letsencrypt
    command:
      - "--api.insecure=true"
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresletsencryptemail=admin@nuclide.systems"
      - "--certificatesresletsencryptstorage=/etc/letsencrypt/acme.json"
EOF

# Start Traefik
cd /opt/stacks/proxy/traefik && docker compose up -d
```

### Step 2: Create Dynamic Configuration

```bash
# Create router rules
cat > /opt/stacks/proxy/traefik/dynamic/router.yml << 'EOF'
http:
  routers:
    litellm-router:
      rule: "Host(`litellm.nuclide.systems`)"
      service: litellm-service
      entrypoints:
        - websecure
      tls:
        certresolver: letsencrypt

    chat-router:
      rule: "Host(`chat.nuclide.systems`)"
      service: chat-service
      entrypoints:
        - websecure
      tls:
        certresolver: letsencrypt

    mcp-router:
      rule: "Host(`mcp.nuclide.systems`)"
      service: mcp-service
      entrypoints:
        - websecure
      tls:
        certresolver: letsencrypt

    s3-router:
      rule: "Host(`s3.nuclide.systems`)"
      service: garage-service
      entrypoints:
        - websecure
      tls:
        certresolver: letsencrypt

  services:
    litellm-service:
      loadBalancer:
        servers:
          - url: "http://192.168.1.40:14000"

    chat-service:
      loadBalancer:
        servers:
          - url: "http://192.168.1.40:14001"

    mcp-service:
      loadBalancer:
        servers:
          - url: "http://192.168.1.40:8080"

    garage-service:
      loadBalancer:
        servers:
          - url: "http://garage:10004"
EOF
```

### Step 3: Add Docker Labels to Services

For any Docker service you want to proxy:

```yaml
# Example: Add to your service docker-compose.yml
services:
  ai-service:
    image: your-service
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.your-service.rule=Host(`your-service.nuclide.systems`)"
      - "traefik.http.routers.your-service.entrypoints=websecure"
      - "traefik.http.routers.your-service.tls.certresolver=letsencrypt"
      - "traefik.http.services.your-service.loadBalancer.server.port=8000"
```

### Step 4: Delete Zoraxy (Optional)

```bash
# Backup Zoraxy configs first
tar -czf /backup/zoraxy-backup.tar.gz /path/to/zoraxy/configs

# Stop and remove Zoraxy
docker rm -f zoraxy || true
```

## API Example (Traefik)

```bash
# Get list of services
curl -u traefik:YOUR_TRAEFIK_API_PASSWORD http://localhost:8080/api/http/routers

# Get Traefik metrics
curl http://localhost:8080/metrics

# Reload configuration (live)
curl -X POST http://localhost:8080/api/http/routers -H "Content-Type: application/json" -d '{...}'
```

## Migration Checklist

- [ ] Deploy Traefik in host network mode
- [ ] Create Let's Encrypt certificate for your domain
- [ ] Migrate all reverse proxy rules to Traefik labels or dynamic config
- [ ] Test SSL certificates work: `curl -k https://your-domain.nuclide.systems`
- [ ] Remove Zoraxy Docker container
- [ ] Update DNS if needed
- [ ] Verify all endpoints: health checks at new URLs

## Benefits

1. **Zero maintenance SSL** - Let's Encrypt auto-renews
2. **API-driven** - No manual Web UI needed
3. **Hot reloading** - Changes apply immediately
4. **Docker-native** - Watches container labels automatically
5. **Enterprise-grade** - Used by major cloud providers