dss/.dss/SUPERVISORD_INSTALLATION.md

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

# 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

# Reread configuration
sudo supervisorctl reread

# Update with new configs
sudo supervisorctl update

3. Start Services

# Start API server
sudo supervisorctl start dss-api

# Start MCP server
sudo supervisorctl start dss-mcp

4. Verify Status

# 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

# 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

# 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

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

   sudo supervisorctl tail dss-api stderr
   sudo supervisorctl tail dss-mcp stderr
   

2. Test commands manually:

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

   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:

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

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

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

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

// 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 Server 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 Server MCP Server",
  "environment": "PYTHONUNBUFFERED=1,DSS_MCP_HOST=0.0.0.0,DSS_MCP_PORT=3457"
}

---

Health Checks

API Server

curl http://localhost:3456/health

Expected:

{
  "status": "degraded",  // or "healthy"
  "vital_signs": {...},
  "version": "0.8.0"
}

MCP Server

curl http://localhost:3457/health

Expected:

{
  "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