Initial commit: Clean DSS implementation
Migrated from design-system-swarm with fresh git history.
Old project history preserved in /home/overbits/apps/design-system-swarm
Core components:
- MCP Server (Python FastAPI with mcp 1.23.1)
- Claude Plugin (agents, commands, skills, strategies, hooks, core)
- DSS Backend (dss-mvp1 - token translation, Figma sync)
- Admin UI (Node.js/React)
- Server (Node.js/Express)
- Storybook integration (dss-mvp1/.storybook)
Self-contained configuration:
- All paths relative or use DSS_BASE_PATH=/home/overbits/dss
- PYTHONPATH configured for dss-mvp1 and dss-claude-plugin
- .env file with all configuration
- Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability
Migration completed: $(date)
🤖 Clean migration with full functionality preserved
This commit is contained in:
Digital Production Factory
205
.dss/DEPLOYMENT_GUIDE.md
Normal file
205
.dss/DEPLOYMENT_GUIDE.md
Normal file
@@ -0,0 +1,205 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user