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

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

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

sudo nginx -t

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

Step 4: Restart Nginx

sudo systemctl reload nginx
# OR
sudo systemctl restart nginx

Step 5: Verify Services

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

location / {
    proxy_pass http://127.0.0.1:3456;  # Vite dev server
    ...
}

After (Production)

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:

   # Trigger some console logs in browser
   # Then check server logs:
   ./admin-ui/scripts/dss-logs.sh
   

4. ✅ Test API endpoint (from browser DevTools console):

   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:

  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