mcp-proc/docs/DEPLOYMENT.md

# Deployment Guide

This guide covers deploying MCP ProcFS Server in production environments.

## Prerequisites

- Linux server (Ubuntu 20.04+, Debian 11+, or similar)
- Node.js 18 or higher
- sudo/root access for system operations
- systemd (for service management)

## Installation on Server

### Option 1: From npm (recommended)

```bash
# Install globally
sudo npm install -g @mcp/procfs-server

# Verify installation
mcp-procfs --version
```

### Option 2: From source

```bash
# Clone repository
git clone https://github.com/cameronrye/activitypub-mcp.git
cd activitypub-mcp/mcp-proc

# Install and build
npm install
npm run build

# Link globally (optional)
sudo npm link
```

## Running as a Service

### systemd Service File

Create `/etc/systemd/system/mcp-procfs.service`:

```ini
[Unit]
Description=MCP ProcFS Server
After=network.target

[Service]
Type=simple
User=mcp-procfs
Group=mcp-procfs
WorkingDirectory=/opt/mcp-procfs
Environment="NODE_ENV=production"
Environment="PORT=3000"
ExecStart=/usr/bin/node /usr/local/lib/node_modules/@mcp/procfs-server/dist/cli-sse.js
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=mcp-procfs

# Security settings
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/log/mcp-procfs

# Required capabilities
CapabilityBoundingSet=CAP_SYS_NICE CAP_SYS_ADMIN CAP_DAC_OVERRIDE
AmbientCapabilities=CAP_SYS_NICE CAP_SYS_ADMIN CAP_DAC_OVERRIDE

[Install]
WantedBy=multi-user.target
```

### Setup Service

```bash
# Create user
sudo useradd -r -s /bin/false mcp-procfs

# Create working directory
sudo mkdir -p /opt/mcp-procfs
sudo chown mcp-procfs:mcp-procfs /opt/mcp-procfs

# Create log directory
sudo mkdir -p /var/log/mcp-procfs
sudo chown mcp-procfs:mcp-procfs /var/log/mcp-procfs

# Reload systemd
sudo systemctl daemon-reload

# Enable and start service
sudo systemctl enable mcp-procfs
sudo systemctl start mcp-procfs

# Check status
sudo systemctl status mcp-procfs

# View logs
sudo journalctl -u mcp-procfs -f
```

## Nginx Reverse Proxy

### Install Nginx

```bash
sudo apt update
sudo apt install nginx
```

### Configure Nginx

Create `/etc/nginx/sites-available/mcp-procfs`:

```nginx
upstream mcp_procfs {
    server 127.0.0.1:3000;
    keepalive 64;
}

server {
    listen 80;
    server_name procfs.example.com;

    # Redirect to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name procfs.example.com;

    # SSL certificates (use Let's Encrypt)
    ssl_certificate /etc/letsencrypt/live/procfs.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/procfs.example.com/privkey.pem;

    # SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;

    # Rate limiting
    limit_req_zone $binary_remote_addr zone=mcp_limit:10m rate=10r/s;
    limit_req zone=mcp_limit burst=20 nodelay;

    # Proxy settings
    location / {
        proxy_pass http://mcp_procfs;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;

        # SSE configuration
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400;
    }

    # API documentation
    location /api-docs {
        proxy_pass http://mcp_procfs/api-docs;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
    }

    # Health check
    location /health {
        proxy_pass http://mcp_procfs/health;
        access_log off;
    }
}
```

### Enable Site

```bash
# Create symlink
sudo ln -s /etc/nginx/sites-available/mcp-procfs /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx
```

## SSL/TLS with Let's Encrypt

```bash
# Install certbot
sudo apt install certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d procfs.example.com

# Auto-renewal is set up automatically
# Test renewal
sudo certbot renew --dry-run
```

## Environment Configuration

Create `/opt/mcp-procfs/.env`:

```bash
NODE_ENV=production
PORT=3000
LOG_LEVEL=info
```

Update systemd service to use env file:

```ini
[Service]
EnvironmentFile=/opt/mcp-procfs/.env
```

## Monitoring

### Prometheus Metrics (future enhancement)

The server can be extended to expose metrics:

```typescript
// Add to server-sse.ts
import promClient from 'prom-client';

const register = new promClient.Registry();
const httpRequestDuration = new promClient.Histogram({
  name: 'http_request_duration_seconds',
  help: 'Duration of HTTP requests in seconds',
  labelNames: ['method', 'route', 'status'],
});
register.registerMetric(httpRequestDuration);

app.get('/metrics', async (req, res) => {
  res.set('Content-Type', register.contentType);
  res.end(await register.metrics());
});
```

### Log Rotation

Create `/etc/logrotate.d/mcp-procfs`:

```
/var/log/mcp-procfs/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 mcp-procfs mcp-procfs
    sharedscripts
    postrotate
        systemctl reload mcp-procfs > /dev/null 2>&1 || true
    endscript
}
```

## Security Hardening

### Firewall (UFW)

```bash
# Allow SSH
sudo ufw allow ssh

# Allow HTTP and HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Enable firewall
sudo ufw enable

# Check status
sudo ufw status
```

### Fail2ban (optional)

Create `/etc/fail2ban/filter.d/mcp-procfs.conf`:

```ini
[Definition]
failregex = ^<HOST> .* "POST /api/.*" 401
            ^<HOST> .* "POST /api/.*" 403
ignoreregex =
```

Create `/etc/fail2ban/jail.d/mcp-procfs.conf`:

```ini
[mcp-procfs]
enabled = true
port = http,https
filter = mcp-procfs
logpath = /var/log/nginx/access.log
maxretry = 5
bantime = 3600
```

## Backup

### Configuration Backup

```bash
#!/bin/bash
# /opt/mcp-procfs/backup.sh

BACKUP_DIR="/var/backups/mcp-procfs"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# Backup configuration
tar -czf $BACKUP_DIR/config_$DATE.tar.gz \
    /etc/systemd/system/mcp-procfs.service \
    /etc/nginx/sites-available/mcp-procfs \
    /opt/mcp-procfs/.env

# Keep only last 7 days
find $BACKUP_DIR -name "config_*.tar.gz" -mtime +7 -delete
```

Add to crontab:

```bash
0 2 * * * /opt/mcp-procfs/backup.sh
```

## Health Checks

### External Monitoring

Use services like UptimeRobot, Pingdom, or custom scripts:

```bash
#!/bin/bash
# health-check.sh

ENDPOINT="https://procfs.example.com/health"
RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" $ENDPOINT)

if [ $RESPONSE -eq 200 ]; then
    echo "OK: Server is healthy"
    exit 0
else
    echo "ERROR: Server returned $RESPONSE"
    exit 1
fi
```

## Performance Tuning

### Node.js Options

Update systemd service:

```ini
[Service]
Environment="NODE_OPTIONS=--max-old-space-size=2048"
```

### Nginx Tuning

Add to nginx.conf:

```nginx
worker_processes auto;
worker_rlimit_nofile 65535;

events {
    worker_connections 4096;
    use epoll;
}
```

## Scaling

### Horizontal Scaling with PM2

```bash
# Install PM2
npm install -g pm2

# Start with cluster mode
pm2 start dist/cli-sse.js -i max --name mcp-procfs

# Save configuration
pm2 save

# Setup startup script
pm2 startup
```

### Load Balancing

Update Nginx upstream:

```nginx
upstream mcp_procfs {
    least_conn;
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;
    server 127.0.0.1:3002;
    server 127.0.0.1:3003;
    keepalive 64;
}
```

## Troubleshooting

### Service won't start

```bash
# Check logs
sudo journalctl -u mcp-procfs -n 50

# Check permissions
sudo -u mcp-procfs /usr/bin/node --version

# Verify installation
which node
node --version
```

### Permission errors

```bash
# Grant capabilities
sudo setcap cap_sys_nice,cap_sys_admin+ep /usr/bin/node

# Or run as root (not recommended)
sudo systemctl edit mcp-procfs
# Add: User=root
```

### High memory usage

```bash
# Monitor with htop
htop

# Check Node.js heap
node --expose-gc --max-old-space-size=512 dist/cli-sse.js
```

## Maintenance

### Updates

```bash
# Stop service
sudo systemctl stop mcp-procfs

# Update package
sudo npm update -g @mcp/procfs-server

# Start service
sudo systemctl start mcp-procfs

# Verify
curl http://localhost:3000/health
```

### Rolling Restart

```bash
# With PM2
pm2 reload mcp-procfs

# With systemd
sudo systemctl restart mcp-procfs
```

## Checklist

- [ ] Server provisioned
- [ ] Node.js installed
- [ ] MCP ProcFS Server installed
- [ ] systemd service configured
- [ ] Service running and enabled
- [ ] Nginx installed and configured
- [ ] SSL certificates obtained
- [ ] Firewall configured
- [ ] Monitoring set up
- [ ] Backups configured
- [ ] Documentation updated
- [ ] Team trained

## Support

For production support:
- GitHub Issues: https://github.com/cameronrye/activitypub-mcp/issues
- Documentation: https://github.com/cameronrye/activitypub-mcp/tree/master/mcp-proc