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
310
.dss/SUPERVISORD_INSTALLATION.md
Normal file
310
.dss/SUPERVISORD_INSTALLATION.md
Normal file
@@ -0,0 +1,310 @@
|
||||
# Supervisord Installation Guide
|
||||
|
||||
**Purpose**: Install systemd service configurations for DSS API and MCP servers
|
||||
|
||||
**Date**: December 6, 2025
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Supervisor installed (`sudo apt install supervisor`)
|
||||
- Admin access to `/etc/supervisor/conf.d/`
|
||||
|
||||
---
|
||||
|
||||
## Installation Steps
|
||||
|
||||
### 1. Copy Configuration Files
|
||||
|
||||
```bash
|
||||
# Copy API server config
|
||||
sudo cp /home/overbits/dss/.dss/supervisord/dss-api.conf \
|
||||
/etc/supervisor/conf.d/dss-api.conf
|
||||
|
||||
# Copy MCP server config
|
||||
sudo cp /home/overbits/dss/.dss/supervisord/dss-mcp.conf \
|
||||
/etc/supervisor/conf.d/dss-mcp.conf
|
||||
```
|
||||
|
||||
### 2. Reload Supervisor
|
||||
|
||||
```bash
|
||||
# Reread configuration
|
||||
sudo supervisorctl reread
|
||||
|
||||
# Update with new configs
|
||||
sudo supervisorctl update
|
||||
```
|
||||
|
||||
### 3. Start Services
|
||||
|
||||
```bash
|
||||
# Start API server
|
||||
sudo supervisorctl start dss-api
|
||||
|
||||
# Start MCP server
|
||||
sudo supervisorctl start dss-mcp
|
||||
```
|
||||
|
||||
### 4. Verify Status
|
||||
|
||||
```bash
|
||||
# Check both services
|
||||
sudo supervisorctl status dss-api dss-mcp
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
dss-api RUNNING pid 12345, uptime 0:00:05
|
||||
dss-mcp RUNNING pid 12346, uptime 0:00:05
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Service Configuration Details
|
||||
|
||||
### DSS API Server (dss-api)
|
||||
|
||||
- **Command**: `python3 -m uvicorn server:app --host 0.0.0.0 --port 3456`
|
||||
- **Directory**: `/home/overbits/dss/tools/api`
|
||||
- **Port**: 3456
|
||||
- **Log**: `/home/overbits/dss/.dss/logs/api.log`
|
||||
- **Environment**:
|
||||
- `DSS_HOST=dss.overbits.luz.uy`
|
||||
- `PYTHONUNBUFFERED=1`
|
||||
|
||||
### DSS MCP Server (dss-mcp)
|
||||
|
||||
- **Command**: `/home/overbits/dss/tools/dss_mcp/start.sh`
|
||||
- **Directory**: `/home/overbits/dss/tools/dss_mcp`
|
||||
- **Port**: 3457
|
||||
- **Log**: `/home/overbits/dss/.dss/logs/mcp.log`
|
||||
- **Environment**:
|
||||
- `PYTHONUNBUFFERED=1`
|
||||
- `DSS_MCP_HOST=0.0.0.0`
|
||||
- `DSS_MCP_PORT=3457`
|
||||
|
||||
---
|
||||
|
||||
## Management Commands
|
||||
|
||||
### Start/Stop/Restart
|
||||
|
||||
```bash
|
||||
# Start
|
||||
sudo supervisorctl start dss-api
|
||||
sudo supervisorctl start dss-mcp
|
||||
|
||||
# Stop
|
||||
sudo supervisorctl stop dss-api
|
||||
sudo supervisorctl stop dss-mcp
|
||||
|
||||
# Restart
|
||||
sudo supervisorctl restart dss-api
|
||||
sudo supervisorctl restart dss-mcp
|
||||
|
||||
# Restart both
|
||||
sudo supervisorctl restart dss-api dss-mcp
|
||||
```
|
||||
|
||||
### View Logs
|
||||
|
||||
```bash
|
||||
# Tail API logs
|
||||
sudo supervisorctl tail -f dss-api
|
||||
|
||||
# Tail MCP logs
|
||||
sudo supervisorctl tail -f dss-mcp
|
||||
|
||||
# View log files directly
|
||||
tail -f /home/overbits/dss/.dss/logs/api.log
|
||||
tail -f /home/overbits/dss/.dss/logs/mcp.log
|
||||
```
|
||||
|
||||
### Status and Info
|
||||
|
||||
```bash
|
||||
# Check status
|
||||
sudo supervisorctl status
|
||||
|
||||
# Show process info
|
||||
sudo supervisorctl pid dss-api
|
||||
sudo supervisorctl pid dss-mcp
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Service Won't Start
|
||||
|
||||
1. **Check logs**:
|
||||
```bash
|
||||
sudo supervisorctl tail dss-api stderr
|
||||
sudo supervisorctl tail dss-mcp stderr
|
||||
```
|
||||
|
||||
2. **Test commands manually**:
|
||||
```bash
|
||||
# Test API server
|
||||
cd /home/overbits/dss/tools/api
|
||||
python3 -m uvicorn server:app --host 0.0.0.0 --port 3456
|
||||
|
||||
# Test MCP server
|
||||
cd /home/overbits/dss
|
||||
./tools/dss_mcp/start.sh
|
||||
```
|
||||
|
||||
3. **Check file permissions**:
|
||||
```bash
|
||||
ls -la /home/overbits/dss/tools/dss_mcp/start.sh
|
||||
# Should be executable: -rwxr-xr-x
|
||||
```
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
If ports 3456 or 3457 are in use:
|
||||
|
||||
```bash
|
||||
# Find process using port
|
||||
sudo lsof -i :3456
|
||||
sudo lsof -i :3457
|
||||
|
||||
# Kill existing process
|
||||
sudo kill <PID>
|
||||
|
||||
# Restart service
|
||||
sudo supervisorctl restart dss-api # or dss-mcp
|
||||
```
|
||||
|
||||
### Import Errors
|
||||
|
||||
If you see `ModuleNotFoundError`:
|
||||
|
||||
```bash
|
||||
# Install missing dependencies
|
||||
pip install mcp httpx fastapi uvicorn sse-starlette
|
||||
|
||||
# Or use requirements file
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Updating Configurations
|
||||
|
||||
After modifying config files:
|
||||
|
||||
```bash
|
||||
# 1. Copy updated configs
|
||||
sudo cp /home/overbits/dss/.dss/supervisord/*.conf \
|
||||
/etc/supervisor/conf.d/
|
||||
|
||||
# 2. Reread and update
|
||||
sudo supervisorctl reread
|
||||
sudo supervisorctl update
|
||||
|
||||
# 3. Restart services
|
||||
sudo supervisorctl restart dss-api dss-mcp
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Uninstallation
|
||||
|
||||
To remove services:
|
||||
|
||||
```bash
|
||||
# 1. Stop services
|
||||
sudo supervisorctl stop dss-api dss-mcp
|
||||
|
||||
# 2. Remove from supervisor
|
||||
sudo rm /etc/supervisor/conf.d/dss-api.conf
|
||||
sudo rm /etc/supervisor/conf.d/dss-mcp.conf
|
||||
|
||||
# 3. Update supervisor
|
||||
sudo supervisorctl reread
|
||||
sudo supervisorctl update
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Alternative: Using sarlo-admin MCP
|
||||
|
||||
If you have access to the sarlo-admin MCP server:
|
||||
|
||||
```javascript
|
||||
// Create API service
|
||||
Use tool: mcp__sarlo-admin__service_create
|
||||
{
|
||||
"service_name": "dss-api",
|
||||
"user": "overbits",
|
||||
"working_dir": "/home/overbits/dss/tools/api",
|
||||
"exec_start": "/usr/bin/python3 -m uvicorn server:app --host 0.0.0.0 --port 3456",
|
||||
"description": "Design System Swarm API Server",
|
||||
"environment": "DSS_HOST=dss.overbits.luz.uy,PYTHONUNBUFFERED=1"
|
||||
}
|
||||
|
||||
// Create MCP service
|
||||
Use tool: mcp__sarlo-admin__service_create
|
||||
{
|
||||
"service_name": "dss-mcp",
|
||||
"user": "overbits",
|
||||
"working_dir": "/home/overbits/dss/tools/dss_mcp",
|
||||
"exec_start": "/home/overbits/dss/tools/dss_mcp/start.sh",
|
||||
"description": "Design System Swarm MCP Server",
|
||||
"environment": "PYTHONUNBUFFERED=1,DSS_MCP_HOST=0.0.0.0,DSS_MCP_PORT=3457"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Health Checks
|
||||
|
||||
### API Server
|
||||
|
||||
```bash
|
||||
curl http://localhost:3456/health
|
||||
```
|
||||
|
||||
Expected:
|
||||
```json
|
||||
{
|
||||
"status": "degraded", // or "healthy"
|
||||
"vital_signs": {...},
|
||||
"version": "0.8.0"
|
||||
}
|
||||
```
|
||||
|
||||
### MCP Server
|
||||
|
||||
```bash
|
||||
curl http://localhost:3457/health
|
||||
```
|
||||
|
||||
Expected:
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"server": "dss-mcp",
|
||||
"version": "0.8.0",
|
||||
"cache_size": 0,
|
||||
"active_sessions": 0
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
After installation:
|
||||
|
||||
1. **Test API endpoints**: `/api/debug/diagnostic`, `/api/debug/workflows`
|
||||
2. **Test MCP tools**: Use Claude Code to call `dss_list_browser_sessions`, etc.
|
||||
3. **Monitor logs**: Watch for errors or issues
|
||||
4. **Test browser integration**: Load dashboard and check browser logger
|
||||
|
||||
---
|
||||
|
||||
**Status**: Ready for installation via admin or sarlo-admin MCP
|
||||
Reference in New Issue
Block a user