Within this article, we’re going to explore an advanced way to declare and start your applications. If you read the previous article on process management with PM2, you’re familiar with starting applications from command line. PM2 offers another way to start applications: by using an app declaration file in JSON format.

This JSON app file allows you to specify the application configuration within a single file.

PM2 Series Overview

App Declaration File

Listing and showing process information from command line is a common way to get an overview of currently active processes, location of log files and process specific information like number of instances.

Starting applications from command line can be kind of complex when chaining all the options like application name, number of instances, error and output log file locations, etc. To avoid those complex commands, PM2 offers you a declaration file to comprehensively define every app which should be started when using this file.

Let’s first get an impression how a JSON app declaration file looks like. We call this file: apps.json.

{
  "apps": [
    {
      "name": "futurestudio-homepage",
      "script": "./homepage/server.js",
      "instances": 2,
      "exec_mode": "cluster",
      "env": {
        "NODE_ENV": "production",
        "PORT": "3000",
      }
    },
    {
      "name": "blog",
      "script": "./blog/index.js",
      "instances": 1,
      "exec_mode": "fork",
      "env": {
        "NODE_ENV": "production",
        "PORT": "4000",
      }
    }
  ]
}

Within the root object, you’re defining an apps array containing all apps which get started by PM2 using this declaration file. Each application declaration is wrapped into its own JSON object. Additionally, each object within the apps array defines multiple app properties. These properties represent the options you would use on PM2’s command line utility.

The exemplary declaration file above defines two apps: fututrestudio-homepage and blog. We can now start both applications by running this .json file with PM2:

pm2 start apps.json  

Of course you can use other PM2 commands referencing this JSON file:

# Start processes
pm2 start apps.json

# Restart processes
pm2 restart apps.json

# (Graceful) Reload processes
pm2 reload apps.json

# Stop processes
pm2 stop apps.json

# Delete processes
pm2 delete apps.json  

Remember: If you’re executing the PM2 commands on the app declaration file, your command will affect each defined application. You can restart, stop, or delete a single application using the command line utility.

Available Options

The following list depicts available options within your JSON app declaration file:

• name: application name, e.g. "blog"
• cwd: app location from where it will be launched, e.g. "/blog"
• args: additional arguments passed to your app, e.g. ["testing"]
• script: the script which will be executed to start an app, e.g. "/blog/app.js,
• node_args: additional Node.js arguments when launching your app, e.g. ["--harmony", " --max-stack-size=102400000"]
• timestamp: format of dates in your log files, e.g. "YYYY-MM-DD HH:mm Z"
• error_file: location of your apps error log file, e.g. "logs/blog.stderr.log"
• out_file: location of your apps out log file, e.g. "logs/blog.stdout.log"
• pid_file: location of your apps .pid file, e.g. "pids/blog.pid"
• instances: number of worker processes for your app. Allowed values: positive integer including 0 or 'max'
• min_uptime: minimum uptime before PM2 starts to restart an app in case of errors, e.g. "20s" (20 seconds), default value is 1s
• max_restarts: maximum restart count before PM2 gives up to get your app online, e.g. 10, default value is 15
• max_memory_restart: maximum memory amount before PM2 restarts your app, e.g. "100M" (100 megabytes), allowed values: "1G", "50M", "4K"
• cron_restart: cronjob pattern to restart your app, e.g. `"0 1 * * *",
• watch: watch the app folder for file changes in restart the app if a change is detected, default value is false, allowed values are true|false
• ignore_watch: regex list of files or folders to be ignored when watching an app, e.g. ["[\\/\\\\]\\./", "node_modules"]
• merge_logs: defines whether the logs of all app worker instances will be merged into the same file, default value is false, allowed values true|false
• exec_interpreter: interpreter of your app, e.g. "node"
• exec_mode: execution mode of your app (can also be defined by the instances field), e.g. "fork", allowed values fork|cluster
• autorestart: if enabled, PM2 will automatically restart apps on crashes, e.g. false, default is true, allowed values true|false
• vizion: integrates version control metadata with PM2, default value is true, allowed values are true|false
• env: environment varibles for your app, specified as a nested object, like env: { "NODE_ENV": "production", "AWESOME_SERVICE_API_TOKEN": "xxx" }

Every command line option is also available within the declaration file. Simplify your app starts by defining a JSON file once and adjust it when necessary. You’re saving a lot time if your app setup gets more complex and you need to reconfigure the app from scratch.

What Comes Next

This week, you’ve learned how to create a JSON file describing your app process(es). This kind of setup is very helpful in complex application starts like passing multiple environment variables to your app processes.

Within the next article, we’ll guide you through the log management of PM2 and show you how to get precise application logs to inspect failure situations.

Having trouble with the JSON app declaration? Leave a comment below or shout out @futurestud_io.

---

Additional Resources

• List of available JSON options with description