Welcome to your journey with PM2, the powerful process manager for Node.js applications. Whether you're a beginner just starting with Node.js or an experienced developer looking to optimize your application management, this guide will walk you through PM2 from the ground up. We'll focus primarily on managing a MERN (MongoDB, Express, React, Node.js) stack application, but the principles apply to any Node.js project.
Ok, before discussing other things. Let’s answer the main question that you may have in your mind and that is - What is PM2?
PM2 is a production-grade process manager for Node.js applications. It is designed to help manage, monitor, and keep applications running continuously. PM2 provides features such as automatic application restarts on failure, and comprehensive log management. This tool simplifies the deployment and management of Node.js applications by enabling efficient resource use and ensuring high availability, making it especially useful for managing web servers, APIs, and complex Node.js services in production environments.
Step 1: Installing PM2
Let's begin our journey by installing PM2. Open your terminal and run:
npm install -g pm2
This command installs PM2 globally on your system, making it available for all your projects.
Step 2: Running Your First Node.js File with PM2
Let's start with a simple Node.js file. Create a file named app.js with the following content:
console.log('Hello, PM2!');
setInterval(() => {
console.log("'I'm still running!");
}, 5000);
Now, let's run this file with PM2:
pm2 start app.js
Congratulations! You've just started your first process with PM2.
Step 3: Running npm Scripts with PM2
As your projects grow more complex, you'll often use npm scripts defined in your package.json file to start your application. PM2 can manage these scripts just as easily as it manages individual files.
Let's use a Next.js application as an example:
- First, ensure your
package.json has a start script. For a Next.js app, it typically looks like this:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
}
}
- To run the production version of your Next.js app with PM2, use the following command:
pm2 start npm --name "next-app" -- start
This tells PM2 to run the npm start command, which in turn runs next start for a Next.js application.
pm2 start npm: Runs the npm command using PM2.
--name "next-app": Names the process for easy identification.
-- start: Passes start as an argument to npm, ensuring that npm runs the start script defined in your package.json.
- If you want to run the development version, you can use:
pm2 start npm --name "next-app-dev" -- run dev
This runs npm run dev, which starts the Next.js development server.
- You can apply the same principle to other npm scripts. For example, if you have a custom script called
server:
pm2 start npm --name "custom-server" -- run server
This approach is not limited to Next.js. You can use it with any Node.js application that uses npm scripts, such as Express.js servers, React applications, or even custom Node.js scripts.
Step 4: Managing Multiple npm Scripts
For complex projects with multiple components, such as a MERN (MongoDB, Express, React, Node.js) stack application, you'll often need to manage several npm scripts simultaneously. PM2's ecosystem file feature is perfect for this scenario, allowing you to define and manage multiple processes in a single configuration file.
Create a file named ecosystem.config.js in your project root. This file will define all the processes PM2 should manage. Here's an expanded example:
module.exports = {
apps: [
{
name: "next-app",
script: "npm",
args: "start",
cwd: "./frontend",
env: {
NODE_ENV: "production",
PORT: 3000
},
env_development: {
NODE_ENV: "development",
PORT: 3000
}
},
{
name: "express-server",
script: "npm",
args: "run server",
cwd: "./backend",
env: {
NODE_ENV: "production",
PORT: 5000
},
env_development: {
NODE_ENV: "development",
PORT: 5000
}
},
]
}
Let's break down the configuration options:
name: A unique identifier for each process.
script: The command to run. Use "npm" for npm scripts.
args: Arguments to pass to the script. For npm scripts, use "start", "run server", etc.
cwd: The working directory for the process. Useful when your frontend and backend are in separate directories.
env: Environment variables for production.
env_development: Environment variables for development.
To start all processes defined in your ecosystem file:
pm2 start ecosystem.config.js
To start processes in development mode:
pm2 start ecosystem.config.js --env development
This approach gives you the flexibility to manage complex applications with multiple components, all through PM2.
Step 5: Basic PM2 Commands
Now that we have a process running, let's learn some basic PM2 commands:
- List running processes:
pm2 list
- Stop a specific process::
pm2 stop next-app
- Restart a specific process:
pm2 restart next-app
- Delete a specific process from PM2:
pm2 delete next-app
- Stop all processes:
pm2 stop all
- Restart all processes:
pm2 restart all
- Delete all processes:
pm2 delete all
Step 6: Monitoring Your Application
- PM2 provides a real-time monitoring tool. Try it out:
pm2 monit
This command opens an interface where you can see CPU usage, memory consumption, and logs for your running processes.
- Display process details:
pm2 show next-app
This command provides detailed information about a specific process, including its configuration, metadata, and recent logs.
Step 7: Reloading Without Downtime
To update your application with zero downtime:
pm2 reload ecosystem.config.js
This command gracefully reloads all processes defined in your ecosystem file, ensuring that your application remains available during updates.
Step 8: Managing Logs
Logs are crucial for understanding what's happening in your application. Here's how to view them:
- View logs:
pm2 logs
- View logs for a specific application:
pm2 logs next-app
- Clear log files:
pm2 flush
- To view only error logs:
pm2 logs --err
Step 9: Automatic Restart on Crashes
One of PM2's most powerful features is its ability to automatically restart applications that crash or stop unexpectedly. This feature ensures high availability and reliability for your Node.js applications.
Here's how it works:
PM2 constantly monitors the processes it manages.
If a process crashes or exits with an error code, PM2 will automatically restart it.
This happens without any manual intervention, minimizing downtime.
Here are some key options that allow you to fine-tune the automatic restart behavior. These options can be added to your ecosystem.config.js file or specified when starting an application.
max_restarts: Sets the maximum number of restarts within a time frame.
min_uptime: Minimum uptime of the app to be considered started.
max_memory_restart: Restarts the app if it exceeds a specified memory limit.
restart_delay: Delay between automatic restarts (in milliseconds).
autorestart: Enables or disables the automatic restart feature.
Let's update the ecosystem.config.js file to include these options:
module.exports = {
apps: [{
name: "my-app",
script: "app.js",
max_restarts: 10,
min_uptime: "5s",
max_memory_restart: "200M",
restart_delay: 4000,
autorestart: true
}]
}
In this configuration:
The app will restart a maximum of 10 times.
The app must run for at least 5 seconds to be considered successfully started.
If the app uses more than 200MB of memory, it will be restarted.
There will be a 4-second delay between restarts.
Automatic restarts are enabled (this is the default, but we're explicitly setting it here).
You can also set these options when starting an app from the command line:
pm2 start app.js --max-restarts 10 --min-uptime 5000 --max-memory-restart 200M --restart-delay 4000
Example: Demonstrating Automatic Restart
Let's create a simple Node.js application that will crash periodically to demonstrate PM2's automatic restart feature.
Create a new file named crash-test.js with the following content:
let count = 0;
setInterval(() => {
console.log(`Running for ${count} seconds`);
count++;
if (count % 10 === 0) {
console.log("Simulating a crash...");
throw new Error("Application crashed!");
}
}, 1000);
This script will run for 10 seconds and then simulate a crash by throwing an error.
Create an ecosystem.config.js file with the following content:
module.exports = {
apps: [{
name: "crash-test",
script: "crash-test.js",
max_restarts: 5,
min_uptime: "3s",
restart_delay: 2000
}]
}
Start the application with PM2:
pm2 start ecosystem.config.js
Monitor the application:
pm2 monit
You'll see in the monitoring interface that every 10 seconds, the application crashes and PM2 automatically restarts it, with a 2-second delay between restarts.
To view the logs and see the crash and restart events:
pm2 logs crash-test
You'll see output similar to this:
0|crash-test | Running for 8 seconds
0|crash-test | Running for 9 seconds
0|crash-test | Simulating a crash...
0|crash-test | Error: Application crashed!
0|crash-test | at Timeout._onTimeout (/path/to/crash-test.js:8:11)
0|crash-test | at listOnTimeout (node:internal/timers:559:17)
0|crash-test | at processTimers (node:internal/timers:502:7)
PM2 | App [crash-test:0] exited with code [1] via signal [SIGINT]
PM2 | App [crash-test:0] starting in -fork mode-
0|crash-test | Running for 0 seconds
0|crash-test | Running for 1 seconds
This example demonstrates how PM2 automatically restarts your application when it crashes, ensuring continuous operation even in the face of unexpected errors. The configuration options we've set limit the number of restarts to 5 and introduce a 2-second delay between restarts, helping to prevent rapid restart loops in case of persistent issues.
Real-world Example: MERN Stack
Here's how you might set up an ecosystem file for a typical MERN stack application:
module.exports = {
apps: [
{
name: "react-frontend",
script: "npm",
args: "start",
cwd: "./client",
env: {
NODE_ENV: "production",
PORT: 3000
}
},
{
name: "express-backend",
script: "npm",
args: "run server",
cwd: "./server",
env: {
NODE_ENV: "production",
PORT: 5000,
MONGODB_URI: "mongodb://localhost:27017/myapp"
}
},
{
name: "mongodb",
script: "mongod",
args: "--port 27017"
}
]
}
This configuration starts a React frontend, an Express.js backend, and a MongoDB instance, all managed by PM2.
By leveraging PM2's ecosystem files, you can efficiently manage complex, multi-component applications, ensuring all parts of your stack start together and are monitored effectively. This approach simplifies deployment, improves maintainability, and gives you fine-grained control over each component of your application.
Conclusion
Congratulations! You've completed your journey from PM2 basics to advanced usage. You've learned how to start simple scripts, manage complex applications, handle logs, use environment variables, and even tackle a full MERN stack. Remember, PM2 is a powerful tool with many more features to explore. As you continue your development journey, don't hesitate to dive into the PM2 documentation for more advanced usage and optimizations.
Happy coding, and may your applications always stay up and running with PM2!
![Cannot redeclare block-scoped variable in TypeScript [Fixed]](/_next/image?url=https%3A%2F%2Fcdn.hashnode.com%2Fres%2Fhashnode%2Fimage%2Fupload%2Fv1701462077875%2Fedc24eaf-2ef6-4ed3-b33f-ab15d254a02f.webp&w=3840&q=75)
