@tehreet/claude-code-router/docs/DEPLOYMENT.md

Enhanced Claude Code router with robust process management, graceful shutdown, and health monitoring

# Claude Code Router - Deployment Guide

This guide covers various deployment options for Claude Code Router with improved process management and monitoring.

## Table of Contents

- [Quick Start](#quick-start)
- [Deployment Options](#deployment-options)
  - [Local Development](#local-development)
  - [PM2 (Recommended)](#pm2-recommended)
  - [Systemd (Linux)](#systemd-linux)
  - [Docker](#docker)
- [Health Monitoring](#health-monitoring)
- [Troubleshooting](#troubleshooting)

## Quick Start

The simplest way to run Claude Code Router:

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Start the service
ccr start

# Check status
ccr status

# Stop the service
ccr stop
```

## Deployment Options

### Local Development

For local development and testing:

```bash
# Start in foreground
npm start

# Or use the CLI
ccr start
```

### PM2 (Recommended)

PM2 provides robust process management with automatic restarts, logging, and monitoring.

#### Installation

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

# Start with PM2
pm2 start ecosystem.config.js

# Save PM2 configuration
pm2 save

# Setup PM2 to start on boot
pm2 startup
```

#### Management Commands

```bash
# View status
pm2 status claude-code-router

# View logs
pm2 logs claude-code-router

# Restart
pm2 restart claude-code-router

# Reload (zero-downtime)
pm2 reload claude-code-router

# Stop
pm2 stop claude-code-router

# Monitor
pm2 monit
```

#### Configuration

The `ecosystem.config.js` file includes:
- Memory limits (512MB)
- Automatic restarts
- Log rotation
- Graceful shutdown (30s timeout)
- Daily restart at 3 AM

### Systemd (Linux)

For production Linux servers, systemd provides native process management.

#### Installation

```bash
# Run the installation script
sudo ./scripts/install-systemd.sh

# Or manually:
sudo cp claude-code-router.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable claude-code-router
sudo systemctl start claude-code-router
```

#### Management Commands

```bash
# Start service
sudo systemctl start claude-code-router

# Stop service
sudo systemctl stop claude-code-router

# Restart service
sudo systemctl restart claude-code-router

# Check status
sudo systemctl status claude-code-router

# View logs
sudo journalctl -u claude-code-router -f

# View last 100 lines
sudo journalctl -u claude-code-router -n 100
```

### Docker

For containerized deployments:

```dockerfile
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY dist ./dist
COPY ecosystem.config.js ./

EXPOSE 3456

# Use PM2 runtime
RUN npm install -g pm2

CMD ["pm2-runtime", "start", "ecosystem.config.js"]
```

Build and run:

```bash
docker build -t claude-code-router .
docker run -d -p 3456:3456 --name ccr claude-code-router
```

## Health Monitoring

The service exposes several health check endpoints:

### Basic Health Check
```bash
curl http://localhost:3456/health
```

Response:
```json
{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "uptime": 3600,
  "pid": 12345
}
```

### Readiness Check
```bash
curl http://localhost:3456/ready
```

Response:
```json
{
  "ready": true,
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

### Liveness Check
```bash
curl http://localhost:3456/alive
```

Response:
```json
{
  "alive": true,
  "pid": 12345,
  "memory": {
    "rss": 52428800,
    "heapTotal": 19988480,
    "heapUsed": 12345678
  },
  "uptime": 3600
}
```

### Integration with Monitoring Tools

#### Prometheus
Add to your `prometheus.yml`:
```yaml
scrape_configs:
  - job_name: 'claude-code-router'
    static_configs:
      - targets: ['localhost:3456']
    metrics_path: '/metrics'
```

#### Kubernetes
Liveness and readiness probes:
```yaml
livenessProbe:
  httpGet:
    path: /alive
    port: 3456
  initialDelaySeconds: 10
  periodSeconds: 30

readinessProbe:
  httpGet:
    path: /ready
    port: 3456
  initialDelaySeconds: 5
  periodSeconds: 10
```

## Configuration

### Environment Variables

- `SERVICE_PORT`: Port to run on (default: 3456)
- `NODE_ENV`: Environment (development/production)
- `HOME`: Home directory for config files

### Process Limits

The service includes resource limits:
- Memory: 512MB (configurable)
- CPU: 80% quota (systemd)
- Graceful shutdown: 30 seconds

## Troubleshooting

### Service Won't Start

1. Check if port is already in use:
   ```bash
   lsof -i :3456
   ```

2. Check PID file:
   ```bash
   cat ~/.claude-code-router/.claude-code-router.pid
   ```

3. Check logs:
   ```bash
   # PM2
   pm2 logs claude-code-router --lines 100
   
   # Systemd
   sudo journalctl -u claude-code-router -n 100
   ```

### High Memory Usage

1. Check current usage:
   ```bash
   ccr status
   ```

2. Restart service:
   ```bash
   ccr restart
   # or
   pm2 restart claude-code-router
   ```

3. Adjust memory limits in `ecosystem.config.js`

### Connection Issues

1. Verify service is running:
   ```bash
   curl http://localhost:3456/health
   ```

2. Check firewall rules:
   ```bash
   sudo iptables -L -n | grep 3456
   ```

3. Check process is listening:
   ```bash
   netstat -tlnp | grep 3456
   ```

### Graceful Shutdown Issues

The service implements a 30-second graceful shutdown:

1. Stops accepting new connections
2. Waits for active requests to complete
3. Cleans up resources
4. Exits cleanly

If shutdown takes too long, check for:
- Long-running requests
- Stuck connections
- Custom shutdown handlers

## Best Practices

1. **Use PM2 or systemd** for production deployments
2. **Monitor health endpoints** regularly
3. **Set up log rotation** to prevent disk space issues
4. **Configure alerts** for service failures
5. **Test graceful shutdown** behavior
6. **Keep configuration in version control**
7. **Document custom modifications**

## Security Considerations

1. Run service as non-root user
2. Use firewall to restrict access
3. Enable HTTPS for production
4. Rotate logs regularly
5. Monitor for unusual activity
6. Keep dependencies updated

## Performance Tuning

1. Adjust memory limits based on load
2. Configure connection timeouts
3. Use load balancer for multiple instances
4. Monitor response times
5. Enable compression for API responses

## Backup and Recovery

1. Backup configuration files:
   ```bash
   ~/.claude-code-router/config.json
   ```

2. Export PM2 configuration:
   ```bash
   pm2 save
   ```

3. Document environment-specific settings

## Support

For issues and questions:
- Check logs first
- Review this documentation
- Submit issues on GitHub
- Check service health endpoints