broswer-automation/app/remote-server/PM2-GUIDE.md

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)

# Install PM2 globally
npm install -g pm2

# Or using the Makefile
make pm2-setup

2. Start the Server

# 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

# 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

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

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

pm2 start ecosystem.config.js --env production

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

Development

pm2 start ecosystem.config.js --env development

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

Staging

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:

# Save current PM2 processes
pm2 save

# Generate startup script
pm2 startup

# Follow the instructions provided by PM2

Monitoring and Management

Real-time Monitoring

pm2 monit

Process Information

pm2 show mcp-remote-server

Resource Usage

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:

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

# 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