Managing Node.js applications on a production server often requires a process manager to ensure your applications run smoothly and recover automatically from crashes. PM2 is one of the most popular process managers for Node.js, offering powerful features such as process monitoring, log management, and cluster mode.

If you're running an application on a Google Cloud Ubuntu instance, you might encounter a situation where PM2 processes are only visible to the user who started them. This can be problematic if your server has multiple users, such as developers, system administrators, or automated deployment scripts. In this blog post, we'll walk through the steps to configure PM2 as a system-wide service, making it accessible to all users on the server.

Why Configure PM2 as a System-Wide Service?

By default, PM2 runs as a process under the user who started it. This means if you SSH into your server as one user and start a PM2 process, that process will not be visible to another user who logs in via SSH. To address this, we can configure PM2 to run as a service at the system level. This approach has several advantages:

• Process Visibility: All users on the server can view and manage PM2 processes.
• Automatic Startup: PM2 will automatically start on system boot, ensuring your applications are always running.
• Centralized Management: Logs and process states are centralized, making it easier to manage your applications.

Prerequisites

Before we begin, ensure that you have the following:

1. A Google Cloud Ubuntu instance.
2. Node.js and npm installed on the instance.
3. PM2 installed globally.

Step 1: Install PM2 Globally

To ensure that all users can access PM2, it should be installed globally. You can install PM2 globally using npm:

sudo npm install -g pm2

This command installs PM2 in the global npm directory, making it available system-wide.

Step 2: Set Up PM2 as a System-Wide Service

Next, we need to set up PM2 to run as a service. This will allow PM2 to manage processes at the system level rather than being tied to a specific user session.

Run the following command to generate the necessary startup script for PM2:

pm2 startup

This command detects the init system used by your Ubuntu instance (typically systemd) and provides a command that needs to be executed with sudo to configure PM2 as a system-wide service. The output will look something like this:

[PM2] Init System found: systemd
[PM2] To setup the Startup Script, copy/paste the following command:
sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u <username> --hp /home/<username>

Here, <username> should be replaced with the username of the user who initially set up PM2. This ensures that the PM2 process is linked to the correct user’s home directory.

Step 3: Execute the Generated Command

Copy the command provided in the output of the previous step and execute it. For example:

sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u johndoe --hp /home/johndoe

This command creates a systemd service that starts PM2 with the correct environment variables and user context.

Step 4: Save the PM2 Process List

If you already have processes running under PM2 that you want to persist across reboots, you need to save the current process list. This creates a dump file that PM2 will use to restore processes when the system starts:

pm2 save

The pm2 save command saves the current list of managed processes to a JSON file in ~/.pm2/dump.pm2. This file is loaded automatically when PM2 starts, ensuring your applications are resurrected after a reboot.

Step 5: Enable the PM2 Service to Start on Boot

To ensure PM2 starts automatically when the system boots, you need to enable the service:

sudo systemctl enable pm2-johndoe

Replace johndoe with the appropriate username. This command enables the PM2 service, ensuring it starts whenever the system boots up.

Step 6: Accessing PM2 with Any User

Now that PM2 is configured as a system-wide service, it should be accessible to any user on the server. To check the status of the processes or to list them, any user can run:

pm2 list

This command will display the list of processes managed by the system-wide PM2 service, regardless of which user is logged in.

Step 7: Additional Configuration for Shared Logs (Optional)

If you need PM2 logs to be accessible by multiple users, you may need to adjust the file permissions or configure PM2 to store logs in a shared directory. This ensures all users can view and manage logs for the processes running under PM2.

To change the log file directory, you can use the following environment variable:

export PM2_HOME=/path/to/shared/pm2/home

Set this in a global configuration file, like /etc/environment, to make it persistent across sessions.

Step 8: Managing PM2 Processes Across Users

Once PM2 is set up as a service, users can manage processes using standard PM2 commands. However, depending on the permissions and user roles, some commands might require sudo access. For example:

sudo pm2 list

This command will list the processes managed by the system-wide PM2 service, making it easier for administrators and developers to collaborate on server management.

Conclusion

Setting up PM2 as a system-wide service on your Ubuntu instance ensures that your Node.js applications are robustly managed and accessible to all users on the server. This setup is particularly useful in environments with multiple users or automated deployment processes, providing a reliable and centralized way to manage applications.

By following the steps outlined in this guide, you can ensure that PM2 is available to all users, your processes are automatically restarted after system reboots, and logs are easily accessible. This not only simplifies server management but also enhances the reliability of your applications in production.

Happy coding!