tombomb122
/
Redmine-Gitea-Sync
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Redmine-Gitea-Sync/PM2_GUIDE.md

10 KiB
Raw Blame History

PM2 Management Guide

Complete guide for managing the Redmine-Gitea Sync Server with PM2.

Quick Start

Install PM2

npm install -g pm2

Start Application

pm2 start ecosystem.config.cjs
pm2 save
pm2 startup

Essential Commands

Process Management

# Start the application
pm2 start ecosystem.config.cjs

# Start in development mode
pm2 start ecosystem.config.cjs --env development

# Stop the application
pm2 stop redmine-gitea-sync

# Restart the application
pm2 restart redmine-gitea-sync

# Reload with zero downtime (cluster mode)
pm2 reload redmine-gitea-sync

# Delete from PM2
pm2 delete redmine-gitea-sync

# Update environment variables and restart
pm2 restart redmine-gitea-sync --update-env

Monitoring

# List all processes
pm2 list
pm2 ls

# Show detailed information
pm2 show redmine-gitea-sync

# Monitor in real-time
pm2 monit

# View resource usage
pm2 status

Log Management

# View logs in real-time
pm2 logs redmine-gitea-sync

# View last 100 lines
pm2 logs redmine-gitea-sync --lines 100

# View only errors
pm2 logs redmine-gitea-sync --err

# View only output
pm2 logs redmine-gitea-sync --out

# Clear logs
pm2 flush

# Follow logs with grep
pm2 logs redmine-gitea-sync | grep ERROR

Save and Restore

# Save current process list
pm2 save

# Resurrect saved process list
pm2 resurrect

# Clear saved process list
pm2 cleardump

Configuration

Ecosystem File

The ecosystem.config.cjs file contains all configuration:

module.exports = {
  apps: [{
    name: 'redmine-gitea-sync',
    script: './server.mjs',
    env: {
      // Your environment variables
    },
    instances: 1,
    exec_mode: 'fork',
    max_memory_restart: '300M',
    // ... other settings
  }]
};

Update Configuration

  1. Edit ecosystem.config.cjs
  2. Restart with updated environment: 
    pm2 restart redmine-gitea-sync --update-env

Multiple Environments

// ecosystem.config.cjs
module.exports = {
  apps: [{
    name: 'redmine-gitea-sync',
    script: './server.mjs',
    env: {
      NODE_ENV: 'production',
      PORT: 3002,
    },
    env_development: {
      NODE_ENV: 'development',
      PORT: 3002,
      LOG_LEVEL: 'debug',
    },
    env_staging: {
      NODE_ENV: 'staging',
      PORT: 3003,
    }
  }]
};

Start with specific environment:

pm2 start ecosystem.config.cjs --env development
pm2 start ecosystem.config.cjs --env staging

Auto-Start on Boot

Setup Startup Script

# Generate startup script for your system
pm2 startup

# This will output a command like:
# sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u yourusername --hp /home/yourusername

# Run the command it outputs
sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u yourusername --hp /home/yourusername

# Save your process list
pm2 save

Disable Startup

pm2 unstartup

Clustering

For high-traffic scenarios, use cluster mode:

Update ecosystem.config.cjs

module.exports = {
  apps: [{
    name: 'redmine-gitea-sync',
    script: './server.mjs',
    instances: 'max',  // or specific number like 4
    exec_mode: 'cluster',
    // ... other settings
  }]
};

Commands

# Start in cluster mode
pm2 start ecosystem.config.cjs

# Scale up/down
pm2 scale redmine-gitea-sync +2  # Add 2 instances
pm2 scale redmine-gitea-sync 4   # Set to 4 instances

# Reload with zero downtime
pm2 reload redmine-gitea-sync

Log Rotation

Install PM2 Log Rotate Module

pm2 install pm2-logrotate

Configure Log Rotation

# Set max file size (default: 10MB)
pm2 set pm2-logrotate:max_size 10M

# Set number of files to keep (default: 10)
pm2 set pm2-logrotate:retain 7

# Enable compression
pm2 set pm2-logrotate:compress true

# Set rotation interval (daily/hourly)
pm2 set pm2-logrotate:rotateInterval '0 0 * * *'  # Daily at midnight

# View configuration
pm2 conf pm2-logrotate

Monitoring and Metrics

PM2 Plus (Optional)

PM2 Plus provides advanced monitoring:

# Link to PM2 Plus
pm2 link <secret_key> <public_key>

# Unlink
pm2 unlink

Custom Metrics

Add to your application:

const pmx = require('pmx');

// Custom metric
const metric = pmx.probe().metric({
  name: 'Sync Operations',
  value: 0
});

// Increment
metric.set(metric.val() + 1);

System Monitoring

# Install system monitoring module
pm2 install pm2-server-monit

# View dashboard
# Access via http://localhost:9615

Troubleshooting

Process Keeps Restarting

# Check error logs
pm2 logs redmine-gitea-sync --err

# View restart count
pm2 list

# Increase restart delay in ecosystem.config.cjs
restart_delay: 5000,
max_restarts: 5,

High Memory Usage

# Check memory
pm2 list
pm2 monit

# View detailed info
pm2 show redmine-gitea-sync

# Adjust memory limit in ecosystem.config.cjs
max_memory_restart: '500M',

Application Not Starting

# Check if port is in use
sudo lsof -i :3002

# Check logs for errors
pm2 logs redmine-gitea-sync --err --lines 50

# Try starting manually to see errors
node server.js

PM2 Not Starting on Boot

# Verify startup is configured
pm2 startup

# Check systemd status
systemctl status pm2-yourusername

# Regenerate startup script
pm2 unstartup
pm2 startup
pm2 save

Logs Not Appearing

# Check log file locations
pm2 show redmine-gitea-sync

# Verify log directory exists and is writable
ls -la ./logs/

# Create logs directory if missing
mkdir -p ./logs

# Restart application
pm2 restart redmine-gitea-sync

Advanced Usage

Watch Mode

Monitor file changes and auto-restart:

// ecosystem.config.cjs
watch: true,
watch_delay: 1000,
ignore_watch: ['node_modules', 'logs', '.git'],

Or from command line:

pm2 start ecosystem.config.cjs --watch

Cron Restart

Restart at specific intervals:

// ecosystem.config.cjs
cron_restart: '0 3 * * *',  // Every day at 3 AM

Max Restarts

Limit restart attempts:

// ecosystem.config.cjs
max_restarts: 10,
min_uptime: '10s',

Environment-Specific Commands

# Production
pm2 start ecosystem.config.cjs --env production

# Development
pm2 start ecosystem.config.cjs --env development

# Staging
pm2 start ecosystem.config.cjs --env staging

PM2 Runtime Configuration

Update PM2

# Update PM2 to latest version
npm install -g pm2@latest

# Update in-memory PM2
pm2 update

PM2 Home Directory

By default: ~/.pm2

Change location:

export PM2_HOME=/path/to/custom/location

Reset PM2

# Kill PM2 daemon
pm2 kill

# Clear everything
rm -rf ~/.pm2

# Restart PM2
pm2 start ecosystem.config.cjs

Integration with CI/CD

Deploy Script Example

#!/bin/bash

# Pull latest code
git pull origin main

# Install dependencies
npm install --production

# Restart with zero downtime
pm2 reload ecosystem.config.cjs

# Check if running
pm2 list

GitHub Actions Example

name: Deploy

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Deploy to server
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USERNAME }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            cd /opt/redmine-gitea-sync
            git pull
            npm install --production
            pm2 reload ecosystem.config.cjs

Performance Tuning

Node.js Options

// ecosystem.config.cjs
node_args: '--max-old-space-size=2048',

Increase File Descriptors

# Check current limit
ulimit -n

# Increase limit (temporary)
ulimit -n 10000

# Permanent: Edit /etc/security/limits.conf
* soft nofile 10000
* hard nofile 10000

Process Priority

# Start with higher priority (lower nice value)
pm2 start ecosystem.config.cjs --node-args="--nice=-10"

Backup and Restore

Backup PM2 Configuration

# Backup process list
pm2 save

# Backup ecosystem file
cp ecosystem.config.cjs ecosystem.config.cjs.backup

# Backup PM2 directory
tar -czf pm2-backup.tar.gz ~/.pm2

Restore

# Restore PM2 directory
tar -xzf pm2-backup.tar.gz -C ~/

# Resurrect processes
pm2 resurrect

Security Best Practices

Run as Dedicated User

# Create user
sudo useradd -r -s /bin/false pm2user

# Set ownership
sudo chown -R pm2user:pm2user /opt/redmine-gitea-sync

# Run PM2 as user
sudo su - pm2user -s /bin/bash -c "pm2 start /opt/redmine-gitea-sync/ecosystem.config.cjs"
sudo su - pm2user -s /bin/bash -c "pm2 save"

# Setup startup as that user
sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u pm2user --hp /home/pm2user

Secure Environment Variables

Never commit sensitive data to version control:

# Protect ecosystem file
chmod 600 ecosystem.config.cjs

# Use external .env file
# In ecosystem.config.cjs:
require('dotenv').config();

env: {
  REDMINE_API_KEY: process.env.REDMINE_API_KEY,
  GITEA_TOKEN: process.env.GITEA_TOKEN,
}

Quick Reference

Most Common Commands

# Start
pm2 start ecosystem.config.cjs

# Status
pm2 list

# Logs
pm2 logs

# Restart
pm2 restart redmine-gitea-sync

# Stop
pm2 stop redmine-gitea-sync

# Monitor
pm2 monit

# Save
pm2 save

Useful Aliases

Add to ~/.bashrc:

alias pm2-status='pm2 list'
alias pm2-logs='pm2 logs redmine-gitea-sync'
alias pm2-restart='pm2 restart redmine-gitea-sync'
alias pm2-sync='cd /opt/redmine-gitea-sync && pm2 logs redmine-gitea-sync'

Additional Resources

Support

For PM2-specific issues:

  • Check PM2 logs: pm2 logs
  • Consult PM2 documentation
  • Search PM2 GitHub issues

For application issues:

  • Check application logs: pm2 logs redmine-gitea-sync
  • Review main documentation
  • Check server health: curl http://localhost:3002/health