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

```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