feat: add PM2 configuration and deployment setup for remote server
- 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
This commit is contained in:
213
app/remote-server/PM2-GUIDE.md
Normal file
213
app/remote-server/PM2-GUIDE.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# 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
|
||||
```
|
Reference in New Issue
Block a user