(Archived) How to use and configure PM2

You have tried to access an archived page. Please go to the new https://root360.atlassian.net/wiki/spaces/KB to find more documents.

1 Specific terminology
2 Used technologies
- 2.1 PM2
  - 2.1.1 Further information
3 Tutorial
- 3.1 Configure services managed by PM2
- 3.2 Check status of services using PM2 list

You will learn how to configure your services using PM2 and how to check the service status of your PM2-managed services.

Specific terminology

We use specific terminlogy in order to describe complex topics which might differ from your understanding. In order to have a common understanding please check our definition beforehand.

deployment directory: The directory in which the application of your role is in if you use the root360 deployment process. Its physical location is usually in a directory below /srv/ on the application instances, and we create a symbolic link to that directory from /var/www/<role> as one of the last steps of the deployment process.
role: A role is a unit of deployment and configuration of your application in the root360 deployment process. A role includes configuration where to get your application from (such as an git repository), environment variables to use during deployment of a new version (such as database passwords), configuration on which application instances your application should be deployed to and application-specific configuration such as custom web server configurations.
application instance: The EC2 instance your application runs on. Contrast with Jumphost and AWS-managed instances such as database instances.

Used technologies

PM2

PM2 is a process manager which can be utilized to run and manage nodesjs applications.

Further information

https://pm2.keymetrics.io/docs/usage/quick-start/

Tutorial

Configure services managed by PM2

To manage your services with PM2 on the root360 platform, you must create an ecosystem file and specify exec_mode: ‘cluster’. See below for a sample adapted from the PM2 documentation:

module.exports = {
  apps : [{
    exec_mode: 'cluster',
    name: "app",
    script: "./app.js",
    env: { NODE_ENV: "development" },
    env_production: { NODE_ENV: "production" }
  }]
}

Please tell us the name of that file in your deployment directory. We will then create configuration to start PM2 with that ecosystem file. You are free to change the content of the ecosystem file and redeploy as long as you keep exec_mode: ‘cluster’ included.

If exec_mode: 'cluster' is not included in your ecosystem file and you deploy a new version of your service our configuration management would not be able to find the processes of the previous version of PM2 and its services and your new services would fail to run.

Check status of services using PM2 list

The linux user www-data with which we are running your PM2 services does not have a home directory (for more information see https://root360.atlassian.net/wiki/spaces/KB/pages/1172111367 ).

To still be able to use pm2 list you need to explicitly set PM2_HOME and call PM2 using www-data. See the example below using the example role web, executed on an application instance where your PM2 services are running:

role=web
sudo -u www-data -H PM2_HOME="/srv/home_${role}/.pm2/" pm2 list
┌─────┬─────────────┬─────────────┬─────────┬─────────┬──────────┬────────┬──────┬───────────┬──────────┬──────────┬──────────┬──────────┐
│ id  │ name        │ namespace   │ version │ mode    │ pid      │ uptime │ ↺    │ status    │ cpu      │ mem      │ user     │ watching │
├─────┼─────────────┼─────────────┼─────────┼─────────┼──────────┼────────┼──────┼───────────┼──────────┼──────────┼──────────┼──────────┤
│ 0   │ web         │ default     │ 1.37.0  │ cluster │ 23570    │ 5D     │ 0    │ online    │ 1.2%     │ 87.0mb   │ www-data │ disabled │
└─────┴─────────────┴─────────────┴─────────┴─────────┴──────────┴────────┴──────┴───────────┴──────────┴──────────┴──────────┴──────────┘