Skip to content

Commit

Permalink
[doc] Remove documenetation specific to forever-monitor
Browse files Browse the repository at this point in the history
  • Loading branch information
@indexzero
indexzero committed Jul 6, 2012
1 parent d9e5faa commit f27cdaa
Showing 1 changed file with 12 additions and 117 deletions.
129 changes: 12 additions & 117 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -82,122 +76,21 @@ 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:

``` js
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:

Expand Down Expand Up @@ -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

0 comments on commit f27cdaa

Please sign in to comment.