Running PM2 and Node.js in Production Environments

At Stream, we build a lot of showcase and example applications to show off the awesome features that our service has to offer. For nearly all of our applications, we host them on an instance - usually DigitalOcean or AWS EC2.

While maintaining your codebase and keeping it relevant is difficult, we've found that the most challenging aspect when it comes to maintaining an application is keeping it alive and running. Additionally, with Node.js being the core language for most of our backend APIs, scaling a single threaded process can be hard to do; that's where PM2 comes in and why we enjoy using it so much.

There are many process managers out there, most notably, StrongLoop's Process Manager, and good ol' SystemD. And then there is PM2, with over 60 million downloads and 25k GitHub stars (and rising!). We like PM2 because simply put, it's easy to use and makes managing a production environment seamless.

PM2 is a battle-tested, production-ready runtime and process manager for Node.js applications. It comes with a built-in load balancer, as well, which makes scaling applications even easier. Best of all, it works on Linux, Windows, and macOS.

With a configuration file (process.json), you specify what processes you want to run and how many you'd like to scale to. When starting PM2, you specify the process.json file and PM2 takes care of the rest (more on process files in a bit).

What all of this means is that PM2 allows you to keep your Node.js applications alive forever, and to reload them with zero downtime when you have updates to your application or server.

Installing PM2

Installing PM2 is a piece of cake. First, you'll want to make sure that you have your process.json file ready to go in your code so you can kick off the process.

If you're on macOS, installing is as simple as running yarn add global pm2. If you're on Linux, Windows, or using a Docker container (yes, it supports Docker as well), follow the instructions here.

If you're curious what it should look like, here is an example of our process_prod.json file for Winds, our open-source RSS and Podcast application:

{
	"apps": [
		{
			"name": "api",
			"cwd": "api/dist",
			"script": "server.js",
			"watch": false
		},
		{
			"name": "conductor",
			"cwd": "api/dist/workers",
			"script": "conductor.js",
			"watch": false
		},
		{
			"name": "rss-worker",
			"cwd": "api/dist/workers",
			"script": "rss.js",
			"instances": 2,
			"exec_mode": "cluster",
			"watch": false
		},
		{
			"name": "podcast-worker",
			"cwd": "api/dist/workers",
			"script": "podcast.js",
			"instances": 2,
			"exec_mode": "cluster",
			"watch": false
		},
		{
			"name": "og-worker",
			"cwd": "api/dist/workers",
			"script": "og.js",
			"instances": 2,
			"exec_mode": "cluster",
			"watch": false
		}
	]
}

View the code on Gist.

As you can see, we're running several processes, and PM2 handles them without any issues, automatically using the Node.js Cluster API to spawn multiple processes.

Tips and Tricks

With any application (or process manager in our case), it's good to know a few tips and tricks from individuals who have previously used it.

Auto Restart

Once it's started, your app is forever alive, auto-restarting after crashes and machine restarts - all with one simple command:

 pm2 startup 

Process Management

No matter how many applications you're running, PM2 has a suite of commands that allow you to manage their respective states. Below are a few of our favorite commands (in no particular order):

• pm2 start process_prod.json - Start process(es) via process JSON file.
• pm2 ls - Show a list of all applications.
• pm2 stop<app> - Stops a specific application.
• pm2 start<app> - Starts a specific application.
• pm2 <app>scale N - Scales the application you specify to N number of instances (can be used to scale up or down).
• pm2 kill - Kills all running applications.
• pm2 restart - Restarts all running applications.
• pm2 reload - Reloads the app configuration (this comes in handy when you modify your application's environment variables).

Process Management

Running the command pm2 monit will return a rich set of data around your application's health. For example, you'll see CPU utilization, memory usage, requests/minute, and more!

Log Management

PM2 has built-in log management. It aggregates log data from all of your applications and writes it to a single source for viewing. You can even tail the logs in real-time to see what's going on behind the scenes with your application. Log Management from PM2 comes with log rotation as well, which is important, especially if you're application is outputting verbose logs on a frequent basis.

There are three commands that I use often, and you should too:

• pm2 logs - Outputs logs from all running applications.
• pm2 logs app - Outputs logs from only the "app" application.
• pm2 flush - Flushes all log data, freeing up disk space.

Remember, the most important thing to do is to enable log rotation. Doing so will split one giant log file into many smaller files that are more manageable for PM2. To do this, run the following command:

pm2 install pm2-logrotate 

More information on Log Management can be found here.

If you're finding that your instance is filling up with logs often, think about using a centralized logging service such as Loggly, Papertrail, or Elk.

Best Practices

Generally, I like to abide by the practices outlined in The Twelve-Factor App. They will allow you to use PM2 to its full advantage. If you haven't read the manifesto, it comes down to these 12 rules:

1. One codebase tracked in revision control, many deploys.
2. Explicitly declare and isolate dependencies.
3. Store config in the environment.
4. Treat backing services as attached resources.
5. Strictly separate build and run stages.
6. Execute the app as one or more stateless processes.
7. Export services via port binding.
8. Scale out via the process model.
9. Maximize robustness with fast startup and graceful shutdown.
10. Keep development, staging, and production as similar as possible.
11. Treat logs as event streams.
12. Run admin/management tasks as one-off processes.

If you follow the rules above, you'll be able to scale any application with PM2 effectively and efficiently with little to no errors.

Final Thoughts

At Stream, we're all big fans of the open-source community and couldn't be happier that PM2 is an open-source project. It allows us to focus on building amazing applications without worrying about the massive overhead that is required to keep an application up and running. With that said, thank you PM2!

If you'd like to know more about Stream and what we do, have a look at our 5-minute tutorial that walks you through how to use our API to build a scalable newsfeed in just a few lines of code.

For those of you reading, I hope you enjoyed this short read and found a couple of tidbits to be helpful. If you have any questions or comments, please leave them in the comments below!

Thank you for reading and happy coding!