Deploying Node.js applications can be streamlined and made more efficient with PM2, a popular process manager. This guide will walk you through the steps of setting up and deploying a Node.js application using PM2, ensuring that you understand the context and rationale behind each action.

Step 1: Install PM2 and dotenv

First, install PM2 and dotenv as development dependencies to manage your application processes and environment variables.

npm install --save-dev pm2 dotenv

Next, install PM2 globally to make it accessible from anywhere on your system.

npm install —global pm2

Step 2: Setup PM2 Deployment Configuration

PM2 offers a deployment system that allows you to deploy your application to remote servers. To set up the deployment configuration for your production environment, run:

pm2 deploy production setup

This command creates a default configuration that you can customize for your specific needs.

Step 3: Configure Environment Variables

Environment variables are crucial for managing configuration settings across different environments (development, production, etc.). Create and configure a .env file for your server:

Navigate to your project directory and copy the example environment file to create your own:

cd /home/username/www/example.com/source
cp .env.example .env

Edit the .env file to set your specific environment variables. You can use vi, nano, or any other text editor:

vi .env

Ensure that your .env file is added to .gitignore to avoid committing sensitive information to version control:

.env

Step 4: Create .env.example

An .env.example file provides a template of the necessary environment variables for other developers or for setting up new environments. Here’s an example:

# envs for your local

DEPLOY_NAME=application.backend
DEPLOY_USER=username
DEPLOY_HOST=localhost
DEPLOY_PATH=/home/username/www/example.com

# envs for your server

DATABASE_URL=mysql://user:[email protected]:3306/database

Step 5: Configure PM2 Ecosystem File

The ecosystem.config.js file is where you define your application and deployment settings for PM2. This file can be customized to fit your deployment workflow:

const dotenv = require('dotenv');
dotenv.config();

module.exports = {
  apps: [
    {
      name: process.env.DEPLOY_NAME,
      script: './src/server.js',
      env: {
        COMMON_VARIABLE: 'true',
      },
      env_production: {
        NODE_ENV: 'production',
      },
    },
  ],

  deploy: {
    production: {
      user: process.env.DEPLOY_USER,
      host: process.env.DEPLOY_HOST,
      ref: 'origin/master',
      repo: '[email protected]:username/repo.git',
      path: process.env.DEPLOY_PATH,
      'post-deploy': [
        'npm install',
        `pm2 reload ecosystem.config.js --env production --name ${process.env.DEPLOY_NAME}`,
      ].join(' && '),
    },
  },
};

This configuration file defines the application settings under apps and the deployment settings under deploy. The post-deploy section specifies commands to run after deploying, such as installing dependencies and reloading the application.

Step 6: Deploy Your Application

Once everything is set up, you can deploy your application with the following command:

pm2 deploy production

This command uses the deployment configuration defined in your ecosystem.config.js to deploy your application to the production environment.