dss/.dss/DEPLOYMENT_GUIDE.md

# DSS Admin UI - Production Deployment Guide

## 🎯 Expert Analysis Summary (Gemini 3 Pro)

**Root Cause**: Public URL https://dss.overbits.luz.uy/admin-ui/index.html returns 401 because:
- Nginx is configured to proxy to Vite dev server (localhost:3456) which is development-only
- No production build is being served
- Basic Auth is enabled (expected)

**Solution**: Configure nginx to serve static files directly and proxy API requests to FastAPI backend.

## ✅ Completed Steps

1. **Production Build**: ✅ `npm run build` completed
   - Output: `/home/overbits/dss/admin-ui/dist/`
   - Console forwarder copied to dist directory

2. **Vite Dev Server**: ✅ Stopped (not needed for production)

3. **FastAPI Backend**: ✅ Running on localhost:8002 (PID 4177150)
   - Endpoint `/api/logs/browser` verified and working

4. **Nginx Config**: ✅ Created at `.dss/nginx-config-dss.overbits.luz.uy.conf`

## 🔧 Manual Steps Required (Requires sudo)

### Step 1: Backup Current Nginx Config

```bash
sudo cp /etc/nginx/sites-available/dss.overbits.luz.uy.conf /etc/nginx/sites-available/dss.overbits.luz.uy.conf.backup-$(date +%Y%m%d)
```

### Step 2: Apply New Nginx Configuration

```bash
sudo cp /home/overbits/dss/.dss/nginx-config-dss.overbits.luz.uy.conf /etc/nginx/sites-available/dss.overbits.luz.uy.conf
```

### Step 3: Test Nginx Configuration

```bash
sudo nginx -t
```

Expected output: `nginx: configuration file /etc/nginx/nginx.conf test is successful`

### Step 4: Restart Nginx

```bash
sudo systemctl reload nginx
# OR
sudo systemctl restart nginx
```

### Step 5: Verify Services

```bash
# Check FastAPI is running
curl -s http://localhost:8002/docs | head -10

# Check nginx is serving static files
curl -k -s https://dss.overbits.luz.uy/ -u username:password | head -20
```

## 📋 Key Configuration Changes

### Before (Development)
```nginx
location / {
    proxy_pass http://127.0.0.1:3456;  # Vite dev server
    ...
}
```

### After (Production)
```nginx
root /home/overbits/dss/admin-ui/dist;
index index.html;

location /api/ {
    proxy_pass http://127.0.0.1:8002;  # FastAPI backend
    ...
}

location / {
    try_files $uri $uri/ /index.html;  # Serve static files
}
```

## 🔍 Service Architecture

```
┌─────────────────────────────────────────────┐
│  https://dss.overbits.luz.uy               │
│  (Public URL with Basic Auth)              │
└─────────────────┬───────────────────────────┘
                  │
            ┌─────▼─────┐
            │   Nginx   │
            │  (Port 443)│
            └─────┬─────┘
                  │
        ┌─────────┴─────────┐
        │                   │
   ┌────▼────┐        ┌────▼────┐
   │  Static │        │   API   │
   │  Files  │        │  Proxy  │
   │  /dist/ │        │  /api/  │
   └─────────┘        └────┬────┘
                           │
                      ┌────▼────┐
                      │ FastAPI │
                      │ :8002   │
                      └─────────┘
```

## 🎯 Port Allocation (Final)

| Service | Port | Status | Purpose |
|---------|------|--------|---------|
| Nginx | 443 | ✅ Running | Public HTTPS endpoint |
| FastAPI | 8002 | ✅ Running | API backend + browser logging |
| Orchestrator | 8000 | ✅ Running | MCP server (unchanged) |
| Storybook | 6006 | ✅ Running | Design system docs |
| ~~Vite Dev~~ | ~~3456~~ | ❌ Stopped | No longer needed |

## 🔐 Browser Logging in Production

The browser console logging system will work automatically because:

1. **Console Forwarder**: Loaded in index.html (first script)
2. **API Endpoint**: `/api/logs/browser` proxied through nginx
3. **Authentication**: Inherits browser's authenticated session
4. **CORS**: Resolved by proxying through same domain

Logs will be written to: `.dss/logs/browser-logs/browser.log`

## 🧪 Testing Checklist

After applying the nginx config:

1. ✅ **Access public URL**: https://dss.overbits.luz.uy/
   - Should show admin UI (after Basic Auth)
   - No more 401 errors

2. ✅ **Check browser console**: Open DevTools
   - Should see: `[Console Forwarder] Initialized. Monitoring active.`

3. ✅ **Verify browser logging**:
   ```bash
   # Trigger some console logs in browser
   # Then check server logs:
   ./admin-ui/scripts/dss-logs.sh
   ```

4. ✅ **Test API endpoint** (from browser DevTools console):
   ```javascript
   fetch('/api/logs/browser', {
     method: 'POST',
     headers: {'Content-Type': 'application/json'},
     body: JSON.stringify({
       logs: [{level: 'info', timestamp: new Date().toISOString(), message: 'Test', data: []}]
     })
   }).then(r => r.json()).then(console.log);
   ```

## 🚨 Troubleshooting

### Issue: 502 Bad Gateway
- **Cause**: FastAPI backend not running
- **Fix**: `cd tools/api && python3 -m uvicorn server:app --host 127.0.0.1 --port 8002 &`

### Issue: 403 Forbidden
- **Cause**: Nginx can't read dist directory
- **Fix**: `chmod -R 755 /home/overbits/dss/admin-ui/dist`

### Issue: Console forwarder not loaded
- **Cause**: File not in dist directory
- **Fix**: Already copied, but verify:
  ```bash
  ls -la /home/overbits/dss/admin-ui/dist/admin-ui/js/utils/console-forwarder.js
  ```

### Issue: API requests fail in browser
- **Cause**: Nginx not proxying /api
- **Fix**: Verify nginx config has `/api/` location block

## 📊 Current Status

- ✅ Production build ready
- ✅ FastAPI backend running
- ✅ Console forwarder integrated
- ✅ Nginx config prepared
- ⏳ **Awaiting**: Apply nginx config with sudo
- ⏳ **Awaiting**: Test public URL

## 📝 Next Steps for User

**YOU NEED TO:**
1. Run the 4 commands in "Manual Steps Required" (requires sudo)
2. Test the public URL: https://dss.overbits.luz.uy/
3. Verify browser logging is working
4. Confirm all services accessible

**Estimated time**: 5 minutes