tessl/npm-pm2

Production process manager for Node.JS applications with a built-in load balancer.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Version Control Integration

Name: tessl/npm-pm2
Author: tessl

PM2 version control integration for managing application deployments with Git. Provides automatic deployment, version navigation, and source code management capabilities for production applications.

Capabilities

Git Integration and Deployment

Manage application deployments using Git repositories with automatic pull, restart, and reload operations.

/**
 * Pull latest changes and restart process
 * @param process_name - Process name or ID to update
 * @param callback - Called when pull and restart completes
 */
function pullAndRestart(process_name: string, callback?: (err: Error, result: any) => void): void;

/**
 * Pull latest changes and reload process (zero-downtime)
 * @param process_name - Process name or ID to update
 * @param callback - Called when pull and reload completes
 */
function pullAndReload(process_name: string, callback?: (err: Error, result: any) => void): void;

/**
 * Pull specific commit and restart
 * @param process_name - Process name or ID
 * @param commit_id - Git commit ID to pull
 * @param callback - Called when operation completes
 */
function pullCommitId(process_name: string, commit_id: string, callback?: (err: Error, result: any) => void): void;

Usage Examples:

const pm2 = require('pm2');

pm2.connect((err) => {
  if (err) throw err;

  // Pull latest changes and restart
  pm2.pullAndRestart('my-app', (err, result) => {
    if (err) throw err;
    console.log('Application updated and restarted');
  });

  // Pull latest changes with zero-downtime reload
  pm2.pullAndReload('my-app', (err, result) => {
    if (err) throw err;
    console.log('Application updated with zero downtime');
  });

  // Pull specific commit
  pm2.pullCommitId('my-app', 'abc123def456', (err, result) => {
    if (err) throw err;
    console.log('Specific commit deployed');
  });
});

Version Navigation

Navigate through version history with backward and forward operations.

/**
 * Move to previous version/commit
 * @param process_name - Process name or ID
 * @param callback - Called when backward navigation completes
 */
function backward(process_name: string, callback?: (err: Error, result: any) => void): void;

/**
 * Move to next version/commit in history
 * @param process_name - Process name or ID
 * @param callback - Called when forward navigation completes
 */
function forward(process_name: string, callback?: (err: Error, result: any) => void): void;

Usage Examples:

// Rollback to previous version
pm2.backward('my-app', (err, result) => {
  if (err) throw err;
  console.log('Rolled back to previous version');
});

// Move forward to next version
pm2.forward('my-app', (err, result) => {
  if (err) throw err;
  console.log('Moved forward to next version');
});

Deployment Configuration

Configure applications for Git-based deployment using ecosystem files.

// ecosystem.config.js with deployment configuration
module.exports = {
  apps: [{
    name: 'my-app',
    script: 'app.js',
    env: {
      NODE_ENV: 'development'
    },
    env_production: {
      NODE_ENV: 'production'
    }
  }],
  
  deploy: {
    production: {
      user: 'deploy',
      host: ['server1.example.com', 'server2.example.com'],
      ref: 'origin/master',
      repo: 'git@github.com:username/my-app.git',
      path: '/var/www/production',
      'pre-deploy-local': '',
      'post-deploy': 'npm install && pm2 reload ecosystem.config.js --env production',
      'pre-setup': '',
      'post-setup': 'ls -la'
    },
    
    staging: {
      user: 'deploy',
      host: 'staging.example.com',
      ref: 'origin/develop',
      repo: 'git@github.com:username/my-app.git',
      path: '/var/www/staging',
      'post-deploy': 'npm install && pm2 restart ecosystem.config.js --env staging'
    }
  }
};

CLI Deployment Commands

PM2 provides CLI commands for deployment operations:

# Setup deployment environment
pm2 deploy ecosystem.config.js production setup

# Deploy to production
pm2 deploy ecosystem.config.js production

# Deploy specific branch
pm2 deploy ecosystem.config.js production --branch feature/new-feature

# Deploy and update specific process
pm2 deploy ecosystem.config.js production update

# Revert to previous deployment
pm2 deploy ecosystem.config.js production revert 1

Deployment Workflow Examples:

# Initial setup on remote server
pm2 deploy ecosystem.config.js production setup

# Deploy latest changes
pm2 deploy ecosystem.config.js production

# Deploy specific commit
pm2 deploy ecosystem.config.js production --commit abc123

# Check deployment status
pm2 deploy ecosystem.config.js production status

# Rollback last deployment
pm2 deploy ecosystem.config.js production revert 1

Advanced Version Control Features

Automatic Deployment with Webhooks

Set up automatic deployments triggered by Git webhooks:

// webhook-handler.js
const pm2 = require('pm2');
const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook/deploy', (req, res) => {
  const { ref, repository } = req.body;
  
  // Only deploy on master branch push
  if (ref === 'refs/heads/master') {
    pm2.connect((err) => {
      if (err) {
        console.error('PM2 connection failed:', err);
        return res.status(500).json({ error: 'PM2 connection failed' });
      }
      
      // Pull latest changes and reload
      pm2.pullAndReload('my-app', (err, result) => {
        pm2.disconnect();
        
        if (err) {
          console.error('Deployment failed:', err);
          return res.status(500).json({ error: 'Deployment failed' });
        }
        
        console.log('Deployment successful');
        res.json({ success: true, message: 'Deployment completed' });
      });
    });
  } else {
    res.json({ message: 'No deployment needed' });
  }
});

app.listen(3001, () => {
  console.log('Webhook handler listening on port 3001');
});

Version Control with Environment Management

Manage different environments with version control:

// Multi-environment deployment
const deployEnvironment = (env, branch) => {
  pm2.connect((err) => {
    if (err) throw err;
    
    console.log(`Deploying ${env} environment from ${branch} branch`);
    
    // Use different processes for different environments
    const processName = `my-app-${env}`;
    
    pm2.pullAndReload(processName, (err, result) => {
      pm2.disconnect();
      
      if (err) {
        console.error(`${env} deployment failed:`, err);
        return;
      }
      
      console.log(`${env} deployment successful`);
    });
  });
};

// Deploy staging from develop branch
deployEnvironment('staging', 'develop');

// Deploy production from master branch
deployEnvironment('production', 'master');

Monitoring Deployment Status

Track deployment history and status:

const pm2 = require('pm2');

// Get deployment information
pm2.connect((err) => {
  if (err) throw err;
  
  pm2.describe('my-app', (err, description) => {
    if (err) throw err;
    
    const proc = description[0];
    if (proc && proc.pm2_env.versioning) {
      console.log('Version Information:');
      console.log('- Repository:', proc.pm2_env.versioning.repo_path);
      console.log('- Branch:', proc.pm2_env.versioning.branch);
      console.log('- Commit:', proc.pm2_env.versioning.revision);
      console.log('- Comment:', proc.pm2_env.versioning.comment);
      console.log('- Update Date:', new Date(proc.pm2_env.versioning.update_time));
    }
    
    pm2.disconnect();
  });
});

Deployment Best Practices

1. Environment Separation

module.exports = {
  apps: [{
    name: 'app-prod',
    script: 'app.js',
    env_production: {
      NODE_ENV: 'production',
      PORT: 3000
    }
  }, {
    name: 'app-staging', 
    script: 'app.js',
    env_staging: {
      NODE_ENV: 'staging',
      PORT: 3001
    }
  }],
  
  deploy: {
    production: {
      // Production deployment config
      user: 'deploy',
      host: 'prod-server.com',
      ref: 'origin/master',
      repo: 'git@github.com:user/app.git',
      path: '/var/www/production'
    },
    
    staging: {
      // Staging deployment config
      user: 'deploy', 
      host: 'staging-server.com',
      ref: 'origin/develop',
      repo: 'git@github.com:user/app.git',
      path: '/var/www/staging'
    }
  }
};

2. Automated Testing in Deployment

module.exports = {
  deploy: {
    production: {
      user: 'deploy',
      host: 'server.com',
      ref: 'origin/master',
      repo: 'git@github.com:user/app.git',
      path: '/var/www/production',
      'pre-deploy': 'git fetch origin master',
      'post-deploy': [
        'npm install',
        'npm run build',
        'npm test',
        'pm2 reload ecosystem.config.js --env production'
      ].join(' && ')
    }
  }
};

3. Rollback Strategy

# Quick rollback commands
pm2 deploy ecosystem.config.js production revert 1  # Rollback 1 deployment
pm2 deploy ecosystem.config.js production revert 2  # Rollback 2 deployments

# Using version control API
pm2.backward('my-app', (err) => {
  if (err) throw err;
  console.log('Rolled back successfully');
});

Core Types

interface DeploymentConfig {
  /** SSH user for deployment */
  user: string;
  /** Target host(s) for deployment */
  host: string | string[];
  /** Git reference to deploy (branch/tag) */
  ref: string;
  /** Git repository URL */
  repo: string;
  /** Deployment path on remote server */
  path: string;
  /** Commands to run before deployment */
  'pre-deploy'?: string;
  /** Commands to run after deployment */
  'post-deploy'?: string;
  /** Commands to run during initial setup */
  'pre-setup'?: string;
  /** Commands to run after initial setup */
  'post-setup'?: string;
}

interface VersionInfo {
  /** Repository path */
  repo_path?: string;
  /** Current branch */
  branch?: string;
  /** Current commit hash */
  revision?: string;
  /** Commit message */
  comment?: string;
  /** Last update timestamp */
  update_time?: number;
}

Install with Tessl CLI