Within the previous PM2 post, we introduced the utility and touched some of its capabilities. This articles moves on to the core of PM2: process management. We show you how to list running process, start and restart new process as well as stop and delete running app servers to shut them down.

Before heading towards the actual content, let’s overview the list of related posts within this series.

PM2 Series Overview

Node.js Process Management

PM2 is written in Node.js and works well with Node.js applications. During the latest development of PM2, the developer fully focussed on the management of Node.js processes. And we at Future Studio use a lot of Node.js applications, that’s why you’ll see all example for that platform. Of course you can adopt the actual PM2 functionality of all tutorials to any other language

Besides Node, PM2 supports other process types like Coffeescript, Ruby, Python, PHP, Shell and Perl. By default, PM2 associates the following file types with respective interpreters.

{
  ".js" : "node",
  ".sh": "bash",
  ".py": "python",
  ".rb": "ruby",
  ".coffee" : "coffee",
  ".php": "php",
  ".pl" : "perl"
}

Start Processes

All theory is worthless if we don’t get our hands dirty. Finally, this is the time to touch your keyboard and start your command line tool of choice. You can try the shown commands on the fly while reading this article. Move your command line into a project folder containing a Node.js (or other supported language) project and start your server:

pm2 start <server.js>  

The command above assumes your Node.js server is started from the server.js file. Whatever your server file is called, you’ll see an overview of started processes containing only your single server. The name of your server will be the filename which you started. Assuming that we started server.js, our overview will look like this:

$ pm2 start server.js
│ App name │ id │ mode │ pid   │ status │ restart │ uptime │ memory     │ watching │
---------------------------------------------------------------------------------------------
│ server   │ 0  │ fork │ 24002 │ online │ 0       │ 0s     │ 36.180 MB  │ disabled │

App Names

Identifying your servers is very important in production environments. Therefore, you should always specify a clearly understandable app name for your server. Pass the -n or --name option flag with the name while starting the server to specifiy a server name.

$ pm2 start server.js -n homepage
│ App name │ id │ mode │ pid   │ status │ restart │ uptime │ memory     │ watching │
---------------------------------------------------------------------------------------------
│ homepage │ 0  │ fork │ 30627 │ online │ 0       │ 0s     │ 5.176 MB   │ disabled │

This little trick will save you lot’s of headache if you’re in a failure situation and you need to identify the erronous server. The more comprehensible name is a simple and effective step to improve your overall process understandability when having multiple servers running on your machine.

PM2 Load Balancing

PM2 has built-in support for load balancing. Use the -i parameter to pass the number of instances while starting your server process. PM2 will handle all the cluster creation internally and abstracts the complexity of starting multiple app instances.

$ pm2 start server.js -n homepage -i 2
│ App name │ id │ mode    │ pid   │ status │ restart │ uptime │ memory      │ watching │
---------------------------------------------------------------------------------------------
│ homepage │ 0  │ cluster │ 31447 │ online │ 0       │ 0s     │ 25.535 MB   │ disabled │
│ homepage │ 1  │ cluster │ 31448 │ online │ 0       │ 0s     │ 17.629 MB   │ disabled │

As you can see in the listing above, the mode switches from fork to cluster and you’ve two instances of homepage running.

Scaling Applications

You can scale running applications by using the pm2 scale command. The command in- or decreases the number of running instances for a given server.

Scaling requires you to start your application in cluster mode. If you’re running a process in fork mode, this single process needs to be deleted and started from scratch in cluster mode.

$ pm2 scale homepage 3
│ App name │ id │ mode    │ pid   │ status │ restart │ uptime │ memory      │ watching │
---------------------------------------------------------------------------------------------
│ homepage │ 0  │ cluster │ 31447 │ online │ 0       │ 65s    │ 81.383 MB   │ disabled │
│ homepage │ 1  │ cluster │ 31448 │ online │ 0       │ 64s    │ 81.828 MB   │ disabled │
│ homepage │ 2  │ cluster │ 31635 │ online │ 0       │ 0s     │ 18.047 MB   │ disabled │

The scale process is seamless and PM2 starts or deletes a server process while scaling up or down.

Common Process Options

• -n --name: app name for process identification. Once your process runs for a month, you’ll probably can’t remember the process called server or app if you didn’t specify a proper name
• -i --instances <number>: number of instances you want to start of your app. For load balancing purposes, it’s obviously required to start multiple app instances. Use either 0 for unlimited which means a process gets spawned for each core available on your machine or a given number to limit the process count
• -a --arguments:

Restart Processes

Once your app gets started with PM2, you’ll see an overview of already running processes (including your newly started server). From now on, you can use the app name or id to manipulate your process. Either a process restart, stop, or delete can be initiated with your app name or the app id.

pm2 restart <process-name|procss-id|all>  

The pm2 restart command will also print the process overview once the execution finished. The restart count increases by 1 for the given process(es) with every restart execution.

PM2 tries to restart failing servers. If your restart count is very high, you should look at your logs and fix the issue.

$ pm2 restart homepage
│ App name │ id │ mode │ pid   │ status │ restart │ uptime │ memory     │ watching │
---------------------------------------------------------------------------------------------
│ homepage │ 0  │ fork │ 35874 │ online │ 1       │ 0s     │ 5.191 MB   │ disabled │

In case of app updates, you may want to stop, update the codebase and restart your server as well to publish all changes. If you use the stop and start commands for this procedure, the restart count won’t increase. Only the pm2 restart command has effect on the restart counter.

Stop Processes

Sometimes you need to stop your Node.js servers for app updates or general system maintance. Shutting down an individual PM2 process can be done with the pm2 stop command:

pm2 stop <process-name|procss-id|all>  

As well as pm2 start and pm2 restart, the pm2 stop command will output the current overview with process and their statusses.

$ pm2 stop homepage
│ App name │ id │ mode │ pid │ status  │ restart │ uptime │ memory │ watching │
-------------------------------------------------------------------------------
│ homepage │ 0  │ fork │ 0   │ stopped │ 1       │ 0      │ 0 B    │ disabled │

The process stops and frees the previously occupied memory. You can use the app name or process id to identify the specific server which should be stopped. Once you finished your operations which required the process stop, use either the pm2 start or pm2 restart command to kick off the process again.

Delete Processes

If you don’t need an app anymore, you can kill the process and delete it from PM2’s process list. The difference between a process stop and delete is that the deletion removes the process generally from PM2’s watchlist. It will delete any process specific data and makes the previously taken app name available again.

pm2 delete <process-name|procss-id|all>  

You probably know what comes next … Exactly, PM2 prints the current process overview after finishing the delete command:

$ pm2 delete homepage
│ App name │ id │ mode │ pid │ status │ restart │ uptime │ memory │ watching │

Since we only started the homepage process throughout this guide, there is no other process left to watch and all used system resources are deallocated free for use.

What Comes Next

This article shows you the core element of PM2: process handling. Now you’re able to start, restart, stop and delete Node.js processes as well as other types like Ruby, Python, PHP, and more.

The next post will show you how to list an overview of current processes and how to show specific process details.

If you’re having trouble with your processes, leave a comment below or tweet us @futurestud_io.

Happy processing :)

---

Additional Resources

• PM2 Process Options for process starts
• PM2 Process Management commands