PM2 is a great and easy to use process manager with support for various programming languages. We at Future Studio love PM2 and use it for all our apps. Each individual application can be started separately using the command line or you can benefit from multiple or just a single JSON configuration to start your processes.

This guide walks you through the setup of having multiple applications within a single JSON file.

PM2 Series Overview

JSON vs. JavaScript vs. YAML

PM2 supports all three file types as the basis for the application definitions and customization. Choose your preferred one and go with it, there are no benefits of deciding for one or another.

We’re fans of JSON and will show your all examples in JSON format. You can simply adopt the snippets to JS or YAML.

Configure Multiple Applications in a Single JSON File

Within a previously published tutorial, you’ve already seen PM2’s capability to handle advanced application configurations using a JSON file. You’ve dozens of options available to customize the behavior of your applications managed by PM2.

Within the JSON file, PM2 uses the apps key as basis for a list of defined applications. Separate each application into an object and provide the defined options with respective values. The following example defines three applications: futurestudio-homepage, futurestudio-worker and futurestudio-api. All three processes have their own entry point (JS file) which is referenced as the value for script.

pm2-apps.json

{
  "apps": [
    {
      "name": "futurestudio-homepage",
      "script": "./server.js",
      "exec_mode": "cluster",
      "instances": 2,
      "node_args": "--max_old_space_size=8192"
    },
    {
      "name": "futurestudio-worker",
      "script": "./worker.js",
      "node_args": "--max_old_space_size=8192"
    },
    {
      "name": "futurestudio-api",
      "script": "./api.js"
    }
  ]
}

PM2 requires you to provide at least the name and script attributes to properly reference and start the defined application. The value for name will be used by PM2 as a reference to the process and must be unique.

To start the defined applications within the pm2-apps.json, use the pm2 command line utility and reference the JSON file. PM2 will automatically detect each application and start them right away.

$ pm2 start pm2.json
[PM2][WARN] Applications futurestudio-homepage, futurestudio-worker, futurestudio-api not running, starting...
[PM2] App [futurestudio-worker] launched (1 instances)
[PM2] App [futurestudio-api] launched (1 instances)
[PM2] App [futurestudio-homepage] launched (2 instances)
┌───────────────────────┬────┬─────────┬──────┬────────┬─────────┬────────┬─────┬───────────┬──────────┐
│ App name              │ id │ mode    │ pid  │ status │ restart │ uptime │ cpu │ mem       │ watching │
├───────────────────────┼────┼─────────┼──────┼────────┼─────────┼────────┼─────┼───────────┼──────────┤
│ futurestudio-api      │ 2  │ fork    │ 6597 │ online │ 0       │ 0s     │ 33% │ 30.3 MB   │ disabled │
│ futurestudio-homepage │ 0  │ cluster │ 6595 │ online │ 0       │ 0s     │ 37% │ 23.9 MB   │ disabled │
│ futurestudio-homepage │ 3  │ cluster │ 6598 │ online │ 0       │ 0s     │ 15% │ 23.1 MB   │ disabled │
│ futurestudio-worker   │ 1  │ fork    │ 6596 │ online │ 0       │ 0s     │ 34% │ 25.0 MB   │ disabled │
└───────────────────────┴────┴─────────┴──────┴────────┴─────────┴────────┴─────┴───────────┴──────────┘
 Use `pm2 show <id|name>` to get more details about an app

The snippet above illustrates the process of starting multiple applications from the pm2-apps.json file (above). In case an application (referenced by name) isn’t already running, PM2 starts it. Once the starting routine for all processes finished, you’ll see the usual overview of processes managed by PM2.

You can’t customize the order in which the processes get started. Read on to learn how you can act on a single application in your process file.

Downsides

Any action applied (start, restart, reload, stop) directly to the JSON configuration file will be passed to all processes within that file. Precisely, if you execute the pm2 restart command directly on your JSON configuration file, all defined processes within that file get restarted immediately.

To only act on a single application within a JSON file, please read the following section.

Act Only a Single Application Within a Process File

In situations where you need to act on your JSON configuration but just want to reference a single application, you can do that by adding the --only argument to the pm2 <action> command. For example, if you want to start the worker process only, do it like this:

$ pm2 start pm2.json --only futurestudio-worker

Once started, you can just manage existing PM2 processes the usual way.

Outlook

Static configurations in JS, JSON or YAML format are a straight forward way to provide complex customizations to your applications that get managed with PM2. You don’t need to remember the individual commands that you’d otherwise apply using the command line utility.

This guide showed you how to define more than a single application within a JSON file and you can apply that to JS and YAML as well. Having multiple application definitions in a single file can benefit you in various scenarios. Keep an eye on actions that are applied with reference to the JSON file, because they’re executed on each defined application. If you want to reference a single application use the --only <app-name> argument.

Do you have further questions on PM2 or Node.js in general? Just let uns know on Twitter @futurestud_io or leave a comment below.

Make it rock & enjoy coding!