robust

Persist and pool processes for Node.js

Installation and Usage

First, install robust as a global npm module:

sudo npm install robust -g

Once installed you can now run robust directly from the command line to automatically start and monitor any node script.

Using robust is as simple as using the robust binary that npm has made available:

cd /path/to/project
robust

Configuration

By default robust will attempt to read a configuration file named robust.json in the current working directory. To use a configuration file with another name or path, use the command line option -config PATH. Robust will work equally well without a configuration file though, so one doesn't need to be present in order to use robust.

By default, robust will run the script called server.js, but this can be changed by using the command line option -script PATH or by adding a script attribute to the configuration file. The path specified should be either an absolute path or relative to the current working directory.

Process Arguments

The script that robust runs will be passed the command line arguments that were given to robust, to change the arguments add an args attribute to the configuration JSON (eg: "args": ["-first", "first value"]), or supply as many arguments as required using the -args command line option. For example:

robust -args "-first" -args "first value"

Each instance of your script will receive the same arguments which will be available as usual as process.argv.

Environment Variables

To customise the environment variables the child scripts receive, you will need to use the configuration JSON file. To send the same environment variables to each process, create an object attribute named defaults. To send different environment variables to each instance, create an array called instances, each item in which is a map of environment variables to supply to child processes of that index.

For example:

{
   "defaults": {
      "SeenByAll": 1,
      "SeenBySome": 2
   },
   "instances": [
      {
         "SeenBySome": 3
      }
   ]
}

Using the extract above will result in all processes having an environment variable SeenByAll set to 1, in the first child instance the value of SeenBySome will be 3, in all others it will be 2.

Process Count

Robust will create at least two child processes and in an environment with multiple cores, will create as many child processes as cores available. To explicitly set the number of processes to create, set the command line option -processes NUMBER or add a processes attribute to the configuration file.

Working Directory

The robust command can be called from anywhere, if you want to reset the current working directory, add the -cwd command line option:

cd /
robust -cwd /path/to/project

This will affect the path that is checked for the robust.json and will also set where the pid file for the service is stored.

Custom PID File

To make it easy to stop or restart existing processes, the process id of the robust managed service is stored in a dot prefixed file in the current working directory. To set the name of the pid file, add the -pid option to the command line:

robust -pid .custom-pid

Using a custom pid file name allows the same working directory to be used for multiple services all managed through robust. Note, the custom pid file name must be in the command line string rather than the configuration file as it is used before the configuration file is read.

Stopping Robust

Stopping a service that is being managed by robust is just a case of adding either --stop to the command line string to stop the service, or --restart to both stop and start the service:

robust --restart

If the robust service was started with a custom working directory, reuse that working directory with the addtional action in the command line, for example:

cd /
robust -cwd /path/to/project --stop