diff --git a/README.md b/README.md index ebcd9a91..eae65509 100644 --- a/README.md +++ b/README.md @@ -4,25 +4,19 @@ A simple CLI tool for ensuring that a given script runs continuously (i.e. forev ## Installation -### Installing npm (node package manager) -``` bash - curl http://npmjs.org/install.sh | sh -``` - -### Installing forever ``` bash $ [sudo] npm install forever -g ``` -**Note:** If you are using forever _programatically_ you should not install it globally. +**Note:** If you are using forever _programatically_ you should install [forever-monitor][0]. ``` bash $ cd /path/to/your/project - $ [sudo] npm install forever + $ [sudo] npm install forever-monitor ``` ## Usage -There are two distinct ways to use forever: through the command line interface, or by requiring the forever module in your own code. +There are two distinct ways to use forever: through the command line interface, or by requiring the forever module in your own code. **Note:** If you are using forever _programatically_ you should install [forever-monitor][0]. ### Using forever from the command line You can use forever to run any kind of script continuously (whether it is written in node.js or not). The usage options are simple: @@ -82,27 +76,14 @@ You can use forever to run any kind of script continuously (whether it is writte forever stop my-daemon.js ``` -There are several examples designed to test the fault tolerance of forever. Here's a simple usage example: +There are [several examples][1] designed to test the fault tolerance of forever. Here's a simple usage example: ``` bash $ forever -m 5 examples/error-on-timer.js ``` -### Using an instance of Forever from node.js -You can also use forever from inside your own node.js code. - -``` js - var forever = require('forever'); - - var child = new (forever.Monitor)('your-filename.js', { - max: 3, - silent: true, - options: [] - }); - - child.on('exit', this.callback); - child.start(); -``` +## Using forever module from node.js +In addition to using a Forever object, the forever module also exposes some useful methods. 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: @@ -110,94 +91,6 @@ You can also use forever from inside your own node.js code. forever.startServer(child); ``` -### Spawning a non-node process -You can spawn non-node processes too. Either set the `command` key in the -`options` hash or pass in an `Array` in place of the `file` argument like this: - -``` js - var forever = require('forever'); - var child = forever.start([ 'perl', '-le', 'print "moo"' ], { - max : 1, - silent : true - }); -``` - -### Options available when using Forever in node.js -There are several options that you should be aware of when using forever. Most of this configuration is optional. - -``` js - { - // - // Basic configuration options - // - 'silent': false, // Silences the output from stdout and stderr in the parent process - 'uid': 'your-UID' // Custom uid for this forever process. (default: autogen) - 'pidFile': 'path/to/a.pid', // Path to put pid information for the process(es) started - 'max': 10, // Sets the maximum number of times a given script should run - 'killTree': true // Kills the entire child process tree on `exit` - - // - // These options control how quickly forever restarts a child process - // as well as when to kill a "spinning" process - // - 'minUptime': 2000, // Minimum time a child process has to be up. Forever will 'exit' otherwise. - 'spinSleepTime': 1000, // Interval between restarts if a child is spinning (i.e. alive < minUptime). - - // - // Command to spawn as well as options and other vars - // (env, cwd, etc) to pass along - // - 'command': 'perl', // Binary to run (default: 'node') - 'options': ['foo','bar'], // Additional arguments to pass to the script, - 'sourceDir': 'script/path' // Directory that the source script is in - - // - // Options for restarting on watched files. - // - 'watch': false // Value indicating if we should watch files. - 'watchIgnoreDotFiles': null // Dot files we should read to ignore ('.foreverignore', etc). - 'watchIgnorePatterns': null // Ignore patterns to use when watching files. - 'watchDirectory': null // Top-level directory to watch from. - - // - // All or nothing options passed along to `child_process.spawn`. - // - 'spawnWith': { - env: process.env, // Information passed along to the child process - customFds: [-1, -1, -1], // that forever spawns. - setsid: false - }, - - // - // More specific options to pass along to `child_process.spawn` which - // will override anything passed to the `spawnWith` option - // - 'env': { 'ADDITIONAL': 'CHILD ENV VARS' } - 'cwd': '/path/to/child/working/directory' - - // - // Log files and associated logging options for this instance - // - 'logFile': 'path/to/file', // Path to log output from forever process (when daemonized) - 'outFile': 'path/to/file', // Path to log output from child stdout - 'errFile': 'path/to/file' // Path to log output from child stderr - } -``` - -### Events available when using an instance of Forever in node.js -Each forever object is an instance of the node.js core EventEmitter. There are several core events that you can listen for: - -* **error** _[err]:_ Raised when an error occurs -* **start** _[process, data]:_ Raised when the target script is first started. -* **stop** _[process]:_ Raised when the target script is stopped by the user -* **restart** _[forever]:_ Raised each time the target script is restarted -* **exit** _[forever]:_ Raised when the target script actually exits (permenantly). -* **stdout** _[data]:_ Raised when data is received from the child process' stdout -* **stderr** _[data]:_ Raised when data is received from the child process' stderr - -## Using forever module from node.js -In addition to using a Forever object, the forever module also exposes some useful methods. Each method returns an instance of an EventEmitter which emits when complete. See the [forever cli commands][1] for sample usage. - ### forever.load (config) _Synchronously_ sets the specified configuration (config) for the forever module. There are two important options: @@ -234,8 +127,10 @@ Removes all log files from the root forever directory that do not belong to curr $ npm test ``` -#### Author: [Charlie Robbins][0] -#### Contributors: [Fedor Indutny](http://github.com/donnerjack13589), [James Halliday](http://substack.net/) +#### License: MIT +#### Author: [Charlie Robbins](http://github.com/indexzero) +#### Contributors: [Fedor Indutny](http://github.com/indutny), [James Halliday](http://substack.net/), [Charlie McConnell](http://github.com/avianflu), [Maciej Malecki](http://github.com/mmalecki) -[0]: http://nodejitsu.com -[1]: https://github.com/nodejitsu/forever/blob/master/lib/forever/cli.js +[0]: http://github.com/nodejitsu/forever-monitor +[1]: http://github.com/nodejitsu/forever-monitor/tree/master/examples +[2]: https://github.com/nodejitsu/forever/blob/master/lib/forever/cli.js \ No newline at end of file