# PM2 Deployment Guide for MCP Remote Server

This guide explains how to run the MCP Remote Server using PM2 for production deployment.

## Prerequisites

1. **Node.js** (v18 or higher)
2. **PM2** (Process Manager)

## Quick Start

### 1. Install PM2 (if not already installed)

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

# Or using the Makefile
make pm2-setup
```

### 2. Start the Server

```bash
# Using Makefile (recommended)
make pm2-start

# Or using npm scripts
npm run pm2:start

# Or directly with PM2
pm2 start ecosystem.config.js
```

### 3. Monitor the Server

```bash
# Check status
make pm2-status
# or
pm2 status

# View logs
make pm2-logs
# or
pm2 logs mcp-remote-server

# Monitor in real-time
pm2 monit
```

## Available Commands

### Makefile Commands

```bash
make pm2-start     # Start server with PM2
make pm2-stop      # Stop server
make pm2-restart   # Restart server
make pm2-status    # Show status
make pm2-logs      # Show logs
make pm2-delete    # Delete PM2 process
```

### NPM Scripts

```bash
npm run pm2:start    # Start with PM2
npm run pm2:stop     # Stop server
npm run pm2:restart  # Restart server
npm run pm2:reload   # Reload (zero-downtime)
npm run pm2:status   # Show status
npm run pm2:logs     # Show logs
npm run pm2:monit    # Open monitoring dashboard
```

## Environment Configuration

The server supports multiple environments configured in `ecosystem.config.js`:

### Production

```bash
pm2 start ecosystem.config.js --env production
```

- PORT: 3040
- HOST: 0.0.0.0
- DOMAIN: https://mcp-browser.qubecare.ai

### Development

```bash
pm2 start ecosystem.config.js --env development
```

- PORT: 3040
- HOST: 0.0.0.0
- DOMAIN: http://localhost:3040

### Staging

```bash
pm2 start ecosystem.config.js --env staging
```

- PORT: 3040
- HOST: 0.0.0.0
- DOMAIN: https://staging-mcp-browser.qubecare.ai

## Logs

Logs are stored in the `logs/` directory:

- `logs/combined.log` - All logs
- `logs/out.log` - Standard output
- `logs/error.log` - Error logs

## Auto-restart on System Boot

To automatically start the server on system boot:

```bash
# Save current PM2 processes
pm2 save

# Generate startup script
pm2 startup

# Follow the instructions provided by PM2
```

## Monitoring and Management

### Real-time Monitoring

```bash
pm2 monit
```

### Process Information

```bash
pm2 show mcp-remote-server
```

### Resource Usage

```bash
pm2 list
```

## Troubleshooting

### Server Won't Start

1. Check if port 3040 is available
2. Verify the build was successful: `npm run build`
3. Check logs: `pm2 logs mcp-remote-server`

### High Memory Usage

The server is configured to restart if memory usage exceeds 1GB. You can adjust this in `ecosystem.config.js`:

```javascript
max_memory_restart: '1G'; // Change to desired limit
```

### Connection Issues

1. Verify the server is running: `make pm2-status`
2. Check health endpoint: `curl http://localhost:3040/health`
3. Review error logs: `pm2 logs mcp-remote-server --err`

## Production Deployment

For production deployment, ensure:

1. **Environment Variables**: Update `.env` file or ecosystem config
2. **Domain Configuration**: Set correct DOMAIN in ecosystem.config.js
3. **SSL/TLS**: Configure reverse proxy (nginx/apache) for HTTPS
4. **Firewall**: Open port 3040 or configure reverse proxy
5. **Monitoring**: Set up external monitoring for the health endpoint

## Security Considerations

1. **Firewall**: Restrict access to port 3040
2. **Reverse Proxy**: Use nginx/apache for SSL termination
3. **Environment Variables**: Keep sensitive data in environment variables
4. **Updates**: Regularly update dependencies

## Example Production Setup

```bash
# 1. Clone and setup
git clone <repository>
cd app/remote-server
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env with production values

# 3. Start with PM2
make pm2-start

# 4. Setup auto-restart
pm2 save
pm2 startup

# 5. Monitor
make pm2-status
```