forever

A simple CLI tool for ensuring that a given script runs continuously (i.e. ...

Process management
foreversd/foreverforever

README

forever

Join the chat at https://gitter.im/foreverjs/forever
Version npmnpm DownloadsBuild StatusDependenciesInline docs
NPM

A simple CLI tool for ensuring that a given script runs continuously (i.e. forever).
Note that this project currently fully depends on the community for implementing fixes and new features. For new installations we encourage you to use pm2 or nodemon

Installation


  1. ``` bash
  2.   $ [sudo] npm install forever -g
  3. ```

Note: If you are using forever _programmatically_ you should install [forever-monitor][0].

  1. ``` bash
  2.   $ cd /path/to/your/project
  3.   $ [sudo] npm install forever-monitor
  4. ```

Usage

There are two ways to use forever: through the command line or by using forever in your code. Note: If you are using forever _programatically_ you should install [forever-monitor][0].

Command Line Usage

You can use forever to run scripts continuously (whether it is written in node.js or not).

Example
  1. ```
  2. forever start app.js
  3. ```

Options
  1. ```
  2.   $ forever --help
  3.   usage: forever [action] [options] SCRIPT [script-options]

  5.   Monitors the script specified in the current process or as a daemon

  7.   actions:
  8.     start               Start SCRIPT as a daemon
  9.     stop                Stop the daemon SCRIPT by Id|Uid|Pid|Index|Script
  10.     stopall             Stop all running forever scripts
  11.     restart             Restart the daemon SCRIPT
  12.     restartall          Restart all running forever scripts
  13.     list                List all running forever scripts
  14.     config              Lists all forever user configuration
  15.     set <key> <val>     Sets the specified forever config <key>
  16.     clear <key>         Clears the specified forever config <key>
  17.     logs                Lists log files for all forever processes
  18.     logs <script|index> Tails the logs for <script|index>
  19.     columns add <col>   Adds the specified column to the output in `forever list`. Supported columns: 'uid', 'command', 'script', 'forever', 'pid', 'id', 'logfile', 'uptime'
  20.     columns rm <col>    Removed the specified column from the output in `forever list`
  21.     columns set <cols>  Set all columns for the output in `forever list`
  22.     columns reset       Resets all columns to defaults for the output in `forever list`
  23.     cleanlogs           [CAREFUL] Deletes all historical forever log files

  25.   options:
  26.     -m  MAX          Only run the specified script MAX times
  27.     -l  LOGFILE      Logs the forever output to LOGFILE
  28.     -o  OUTFILE      Logs stdout from child script to OUTFILE
  29.     -e  ERRFILE      Logs stderr from child script to ERRFILE
  30.     -p  PATH         Base path for all forever related files (pid files, etc.)
  31.     -c  COMMAND      COMMAND to execute (defaults to node)
  32.     -a, --append     Append logs
  33.     -f, --fifo       Stream logs to stdout
  34.     -n, --number     Number of log lines to print
  35.     --pidFile        The pid file
  36.     --uid            DEPRECATED. Process uid, useful as a namespace for processes (must wrap in a string)
  37.                      e.g. forever start --uid "production" app.js
  38.                          forever stop production
  39.     --id             DEPRECATED. Process id, similar to uid, useful as a namespace for processes (must wrap in a string)
  40.                      e.g. forever start --id "test" app.js
  41.                          forever stop test
  42.     --sourceDir      The source directory for which SCRIPT is relative to
  43.     --workingDir     The working directory in which SCRIPT will execute
  44.     --minUptime      Minimum uptime (millis) for a script to not be considered "spinning"
  45.     --spinSleepTime  Time to wait (millis) between launches of a spinning script.
  46.     --colors         --no-colors will disable output coloring
  47.     --plain          Disable command line colors
  48.     -d, --debug      Forces forever to log debug output
  49.     -v, --verbose    Turns on the verbose messages from Forever
  50.     -s, --silent     Run the child script silencing stdout and stderr
  51.     -w, --watch      Watch for file changes
  52.     --watchDirectory Top-level directory to watch from
  53.     --watchIgnore    To ignore pattern when watch is enabled (multiple option is allowed)
  54.     -t, --killTree   Kills the entire child process tree on `stop`
  55.     --killSignal     Support exit signal customization (default is SIGKILL),
  56.                      used for restarting script gracefully e.g. --killSignal=SIGTERM
  57.                      Any console output generated after calling `forever stop/stopall` will not appear in the logs
  58.     -h, --help       You're staring at it

  60.   [Long Running Process]
  61.     The forever process will continue to run outputting log messages to the console.
  62.     ex. forever -o out.log -e err.log my-script.js

  64.   [Daemon]
  65.     The forever process will run as a daemon which will make the target process start
  66.     in the background. This is extremely useful for remote starting simple node.js scripts
  67.     without using nohup. It is recommended to run start with -o -l, & -e.
  68.     ex. forever start -l forever.log -o out.log -e err.log my-daemon.js
  69.         forever stop my-daemon.js
  70. ```

There are [several examples][1] designed to test the fault tolerance of forever. Here's a simple usage example:

  1. ``` bash
  2.   $ forever -m 5 examples/error-on-timer.js
  3. ```

JSON Configuration Files


In addition to passing forever the path to a script (along with accompanying options, described above), you may also pass forever the path to a JSON file containing these options. For example, consider an application with the following file structure:

  1. ```
  2. .
  3. ├── forever
  4. │   └── development.json
  5. └── index.js

  7. // forever/development.json
  8. {
  9. // Comments are supported
  10.     "uid": "app",
  11.     "append": true,
  12.     "watch": true,
  13.     "script": "index.js",
  14.     "sourceDir": "/home/myuser/app",
  15.     "logFile": "/home/myuser/logs/forever.log",
  16.     "outFile": "/home/myuser/logs/out.log",
  17.     "errFile": "/home/myuser/logs/error.log"
  18. }
  19. ```

This application could be started with forever, as shown below:

  1. ``` bash
  2. $ forever start ./forever/development.json
  3. ```

Absolute paths to such configuration files are also supported:

  1. ``` bash
  2. $ forever start /home/myuser/app/forever/development.json
  3. ```

Note: Forever parses JSON configuration files using shush, allowing the use of in-line comments within such files.

Multi-App Configuration Files


JSON configuration files can also be used to define the startup options for multiple applications, as shown below.

  1. ```
  2. [
  3.   {
  4.     // App1
  5.     "uid": "app1",
  6.     "append": true,
  7.     "watch": true,
  8.     "script": "index.js",
  9.     "sourceDir": "/home/myuser/app1"
  10.   },
  11.   {
  12.     // App2
  13.     "uid": "app2",
  14.     "append": true,
  15.     "watch": true,
  16.     "script": "index.js",
  17.     "sourceDir": "/home/myuser/app2",
  18.     "args": ["--port", "8081"]
  19.   }
  20. ]
  21. ```

Using In Your Code

The forever module exposes some useful methods to use in your code. Each method returns an instance of an EventEmitter which emits when complete. See the [forever cli commands][2] for sample usage.

Remark: As of forever@0.6.0 processes will not automatically be available in forever.list(). In order to get your processes into forever.list() or forever list you must instantiate the forever socket server:

  1. ``` js
  2.   forever.startServer(child);
  3. ```

This method takes multiple forever.Monitor instances which are defined in the forever-monitor dependency.

forever.load (config)

_Synchronously_ sets the specified configuration (config) for the forever module. There are two important options:

Option    | Description                                       | Default
root      | Directory to put all default forever log files    | forever.root
pidPath   | Directory to put all forever *.pid files          | [root]/pids
sockPath  | Directory for sockets for IPC between workers     | [root]/sock
loglength | Number of logs to return in forever tail        | 100
columns   | Array of columns to display when format is true | forever.config.get('columns')
debug     | Boolean value indicating to run in debug mode     | false
stream    | Boolean value indicating if logs will be streamed | false

forever.start (file, options)

Starts a script with forever. The options object is what is expected by the Monitor of forever-monitor.

forever.startDaemon (file, options)

Starts a script with forever as a daemon. WARNING: Will daemonize the current process. The options object is what is expected by the Monitor of forever-monitor.

forever.stop (index)

Stops the forever daemon script at the specified index. These indices are the same as those returned by forever.list(). This method returns an EventEmitter that raises the 'stop' event when complete.

forever.stopAll (format)

Stops all forever scripts currently running. This method returns an EventEmitter that raises the 'stopAll' event when complete.

The format parameter is a boolean value indicating whether the returned values should be formatted according to the configured columns which can set with forever columns or programmatically forever.config.set('columns').

forever.list (format, callback)

Returns a list of metadata objects about each process that is being run using forever. This method will return the list of metadata as such. Only processes which have invoked forever.startServer() will be available from forever.list()

The format parameter is a boolean value indicating whether the returned values should be formatted according to the configured columns which can set with forever columns or programmatically forever.config.set('columns').

forever.tail (target, options, callback)

Responds with the logs from the target script(s) from tail. There are two options:

length (numeric): is is used as the -n parameter to tail.
stream (boolean): is is used as the -f parameter to tail.

forever.cleanUp ()

Cleans up any extraneous forever *.pid files that are on the target system. This method returns an EventEmitter that raises the 'cleanUp' event when complete.

forever.cleanLogsSync (processes)

Removes all log files from the root forever directory that do not belong to current running forever processes. Processes are the value returned from Monitor.data in forever-monitor.

forever.startServer (monitor0, monitor1, ..., monitorN)

Starts the forever HTTP server for communication with the forever CLI. NOTE: This will change your process.title. This method takes multiple forever.Monitor instances which are defined in the forever-monitor dependency.

Logging and output file locations


By default forever places all of the files it needs into /$HOME/.forever. If you would like to change that location just set the FOREVER_ROOT environment variable when you are running forever:

  1. ```
  2. FOREVER_ROOT=/etc/forever forever start index.js
  3. ```

Make sure that the user running the process has the appropriate privileges to read & write to this directory.

Run Tests


  1. ``` bash
  2.   $ npm test
  3. ```

License: MIT

Author: Charlie Robbins

Maintainer: Igor Savin

Contributors: Fedor Indutny, James Halliday, Charlie McConnell, Maciej Malecki, John Lancaster


[0]: https://github.com/foreverjs/forever-monitor
[1]: https://github.com/foreverjs/forever-monitor/tree/master/examples
[2]: https://github.com/foreverjs/forever/blob/master/lib/forever/cli.js