PM2 & PM2 ECOSYSTEM
If you deploy nodeJS applications, chances are that you must have used pm2, but for emphasis sake:
PM2 is a production process manager for Node.js applications with a built-in load balancer. It allows you to keep applications alive forever, to reload them without downtime and to facilitate common system admin tasks.
In much simpler terms, pm2 helps you manage servers/services, and keep them running always. — So typical when you develop you use the node or the nodemon command to run your servers locally, but after development, you stop the process. When you deploy your applications online, you need your application(s) running always on your cloud server so that it can be accessible always.
Setting Up pm2
It is quite easy to set up and install pm2.
Usually, I install globally
npm install pm2 -g
To start your service with pm2, In your project folder where you have the entry file, you start your server entry file (index.js, app.js, server.js, etc)
pm2 start index.js.
Most times, I pass the ‘- -w’ flag so that pm2 can watch for changes like when I pull from a repository or install a package or directly edit files in my project. Basically
It watches for any changes. Then my command will look like
pm2 start index.js --w
You can set up multiple servers but I advise naming them separately so you can identify them in the pm2 list. I will elaborate more on running multiple servers later in the post when I talk more about the pm2 ecosystem
My frequently used pm2 commands.
# To see the logs of my pm2 processes
pm2 log
# To show all running processes
pm2 list
# To stop an application. index.js here is the name of the app we started earlier and should also be the name of your app.
pm2 stop index.js
I rarely use these commands, but if you want to carry out bulk actions
pm2 reload all
pm2 stop all
pm2 start all
PM2 ECOSYSTEM
PM2 Ecosystem empowers your process management workflow. It allows you to fine-tune the behavior, options, environment variables, logs files of each application via a process file. It’s particularly useful for micro-service-based applications.
When you have multiple services on a server, a pm2 ecosystem is ideal for managing them.
Usually, I create the ecosystem file in the root folder of each service as part of my configuration so that this ships as part of the project files. The convention is to name the file ecosystem.config.js, but this canoe generated for you by npm. To generate, run the command
pm2 ecosystem
This command will generate a sample ecosystem file. If you created the file yourself below is a sample of how your ecosystem should be:
You notice the apps is an array of objects. Yes, this is so you can have multiple applications set up in one ecosystem file. Each application will be an object in the array.
It is also noteworthy that you do not need to set up all your applications in one ecosystem file, you can have multiple ecosystem files in this format at the root of each individual project. At run time, pm2 will read all individually wherever they are located and run your servers. This is the method I employ in my applications.
In your application object described in the ecosystem have some self-explanatory values that determine how your application will be set up, like the name — (remember each application on a server should have a unique name), the script is your entry file ( app.js, index.js, server.js, etc), then your different environment variables.
Below is attached a more comprehensive ecosystem file from one of my projects
Another example from another project with a more simplified set up that gets the work done
To read more about the configurations of pm2 files see — https://pm2.keymetrics.io/docs/usage/application-declaration/
PM2 Ecosystem commands
Remember when I said you can write individual ecosystem files for each service without putting them all together. To start all your ecosystem files in your server in any folder. The following commands can be used to manage your applications
# Start all applications
pm2 start ecosystem.config.js
# Start only the app named pod-service
pm2 start ecosystem.config.js — only pod-service
# Stop all
pm2 stop ecosystem.config.js
# Restart all
pm2 start ecosystem.config.js
## Or
pm2 restart ecosystem.config.js
# Reload all
pm2 reload ecosystem.config.js
# Delete all
pm2 delete ecosystem.config.js
You can also act on a particular application by using its name and the option — only <app_name>:
pm2 start ecosystem.config.js — only api-app
pm2 restart ecosystem.config.js — only api-app
pm2 reload ecosystem.config.js — only api-app
pm2 delete ecosystem.config.js — only api-app
For multiple processes use:
pm2 start ecosystem.config.js — only “api-app,worker-app”
You may have noticed that we declared environment-specific variables with the attribute env_* (e.g. env_production, env_staging…). They can be switched easily. You just need to specify the — env <environment_name> when acting on the application declaration.
# Inject what is declared in env_production
pm2 start process.json — env production
# Inject what is declared in env_staging
pm2 restart process.json — env staging
I’m hoping this helps you get around pm2 settings and configurations.
Happy Hacking. 👨💻🧑💻👩💻