f4ca680532
- Add Makefile with convenient PM2 commands for development and production - Add ecosystem.config.js with production/staging/dev environment configurations - Add comprehensive PM2-GUIDE.md documentation for deployment - Update package.json with PM2-specific npm scripts - Fix Chrome extension URL handling to omit standard ports (443/80) - Hide embedding model and semantic engine sections in popup UI
214 lines
3.9 KiB
Markdown
214 lines
3.9 KiB
Markdown
# 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
|
|
```
|