/
Autostart Profoundjs with PM2

Autostart Profoundjs with PM2

PM2 is a third-party process manager and is not part of Profound.js. The steps on this page are provided as a convenience; the PM2 project’s own documentation is the authoritative reference (https://pm2.keymetrics.io/docs/usage/quick-start/). On IBM i, use the STRTCPSVR/ENDTCPSVR commands instead (see Starting and Ending Profound.js Instances).

Overview

PM2 runs applications in the background and provides log management, automatic restart policies, and application monitoring, among other features. This page describes how to use PM2 to keep a Profound.js instance running on Windows, including registering it as a Windows Service so that it starts automatically after a reboot.

With PM2 you can:

  • Start, stop, and list applications - for example pm2 start apps/app1.js;

  • Load a predefined configuration - pm2 reload ecosystem.config.js;

  • Save the current configuration - pm2 save;

  • Restore a saved configuration - pm2 resurrect.

Table of Contents

Installation

Installing PM2

Install PM2 globally with npm:

npm install pm2 -g

Starting an Application

From within your Profound.js installation folder, run:

pm2 start start.js

This creates a default PM2 home folder under C:\Users\<username>\.pm2, which stores the PM2-related files.

Changing the PM2 Home Folder Location

The default PM2 home is inside a user profile, which the Windows Service account may not be able to reach. Move it to a neutral location such as c:\pm2home\.pm2:

  1. Create a new folder c:\pm2home\;

  2. Copy the .pm2 folder from C:\Users\<username>\ to c:\pm2home\;

  3. Create a new PM2_HOME environment variable at System level, not User level, and set the value to c:\pm2home\.pm2 (see the images below);

  4. Close all open terminal windows, or restart Windows;

  5. Confirm that PM2_HOME is set correctly:

    REM Command Prompt echo %PM2_HOME% REM Windows Terminal / PowerShell echo $Env:PM2_HOME

Creating a Configuration File

When managing multiple applications with PM2, use a JavaScript configuration file to organize them. From the c:\pm2home\ directory created above, generate one with:

pm2 init simple

This creates a file named ecosystem.config.js. In it you can give each start.js a meaningful name – for example Production, QA, or Development – along with the location of the script:

The exec_mode property defines how the application runs. It accepts either fork or cluster. Fork mode is useful when using PM2 with languages such as PHP or Python; cluster mode is intended for Node.js applications and uses the Node.js cluster module underneath (see Profound.js Clustering).

Launching the Configuration

From the c:\pm2home\ directory, run:

pm2 start ecosystem.config.js

This launches every environment defined in the configuration file.

Saving the Configuration

Save the current process list so PM2 can restore it later:

pm2 save

Creating a Windows Service

Using pm2-windows-service

Create a Windows Service with the pm2-windows-service Node module. This allows the PM2 instances to start automatically.

  1. Install the module:

    npm install -g pm2-windows-service

  2. As administrator, open a command line and run:

    pm2-service-install -n PM2

  3. Answer the prompts as follows:

    ? Perform environment setup (recommended)? Yes ? Set PM2_HOME? Yes ? PM2_HOME value (this path should be accessible to the service user and should not contain any "user-context" variables [e.g. %APPDATA%]): c:\pm2home\.pm2\ ? Set PM2_SERVICE_SCRIPTS (the list of start-up scripts for pm2)? No ? Set PM2_SERVICE_PM2_DIR (the location of the global pm2 to use with the service)? [recommended] Yes ? Specify the directory containing the pm2 version to be used by the service C:\USERS\<USER>\APPDATA\ROAMING\NPM\node_modules\pm2\index.js PM2 service installed and started.

This creates a Windows Service called PM2:

Testing

  1. Restart Windows;

  2. Just after the restart, open a command prompt as Administrator and run pm2 status. The application should already be running.

At this point your Node.js programs are set up as a Windows Service that loads automatically on restart.

Common PM2 Commands

Listing Applications

pm2 list

Managing Applications

pm2 stop <app_name|namespace|id|'all'|json_conf> pm2 restart <app_name|namespace|id|'all'|json_conf> pm2 delete <app_name|namespace|id|'all'|json_conf>

Inspecting a Single Application

pm2 describe <id|app_name>

Monitoring Logs and Metrics

pm2 monit

Log Management

Standard, raw, JSON, and formatted output are available:

pm2 logs # Display logs for all applications pm2 logs APP-NAME # Display APP-NAME logs pm2 logs --json # JSON output pm2 logs --format # Formatted output pm2 flush # Flush all logs pm2 reloadLogs # Reload all logs

Making Changes to the Configuration File

PM2 keeps a saved copy of the process list, so editing ecosystem.config.js is not enough on its own – the old processes must be removed and the new configuration saved:

  1. Stop the current PM2 processes:

    pm2 stop all

  2. Delete the current instances:

    pm2 delete all

  3. Save the removal:

    pm2 save

  4. Reload the configuration file from the c:\pm2home\ directory:

    pm2 start ecosystem.config.js

  5. Save the new configuration:

    pm2 save

Removing the Windows Service

Open a command prompt as Administrator and run:

pm2-service-uninstall

Further Reading