Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 136 lines (104 sloc) 6.439 kb
d000278 @AvianFlu [docs] Add Travis CI badge to README.
AvianFlu authored
1 # forever [![Build Status](https://secure.travis-ci.org/nodejitsu/forever.png)](http://travis-ci.org/nodejitsu/forever)
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
2
3 A simple CLI tool for ensuring that a given script runs continuously (i.e. forever).
4
5 ## Installation
6
725d11d @indexzero [doc] Update README.md
indexzero authored
7 ``` bash
8 $ [sudo] npm install forever -g
a49483d @indexzero [doc] Updated README.md
indexzero authored
9 ```
725d11d @indexzero [doc] Update README.md
indexzero authored
10
f27cdaa @indexzero [doc] Remove documenetation specific to `forever-monitor`
indexzero authored
11 **Note:** If you are using forever _programatically_ you should install [forever-monitor][0].
725d11d @indexzero [doc] Update README.md
indexzero authored
12
13 ``` bash
14 $ cd /path/to/your/project
f27cdaa @indexzero [doc] Remove documenetation specific to `forever-monitor`
indexzero authored
15 $ [sudo] npm install forever-monitor
a49483d @indexzero [doc] Updated README.md
indexzero authored
16 ```
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
17
270d976 @ded preferGlobal
ded authored
18 ## Usage
f27cdaa @indexzero [doc] Remove documenetation specific to `forever-monitor`
indexzero authored
19 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].
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
20
21 ### Using forever from the command line
22 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:
23
a49483d @indexzero [doc] Updated README.md
indexzero authored
24 ```
7d7398b @indexzero [doc] Update README.md with watch file options
indexzero authored
25 $ forever --help
061d14f @mmalecki [fix doc] Fix README to match flatiron refactor
mmalecki authored
26 usage: forever [options] [action] SCRIPT [script-options]
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
27
a49483d @indexzero [doc] Updated README.md
indexzero authored
28 Monitors the script specified in the current process or as a daemon
0d5a789 @indexzero [dist] Version bump.
indexzero authored
29
a49483d @indexzero [doc] Updated README.md
indexzero authored
30 actions:
1dac9f4 @indexzero [doc] Updated README.md
indexzero authored
31 start Start SCRIPT as a daemon
32 stop Stop the daemon SCRIPT
33 stopall Stop all running forever scripts
34 restart Restart the daemon SCRIPT
0d5e893 @indexzero [api] Added `forever restartall` and `forever.restartAll()`. Fixes #131
indexzero authored
35 restartall Restart all running forever scripts
1dac9f4 @indexzero [doc] Updated README.md
indexzero authored
36 list List all running forever scripts
37 config Lists all forever user configuration
38 set <key> <val> Sets the specified forever config <key>
39 clear <key> Clears the specified forever config <key>
e740fb6 @indexzero [doc] Update README.md for `forever logs *` commands
indexzero authored
40 logs Lists log files for all forever processes
41 logs <script|index> Tails the logs for <script|index>
1dac9f4 @indexzero [doc] Updated README.md
indexzero authored
42 columns add <col> Adds the specified column to the output in `forever list`
43 columns rm <col> Removed the specified column from the output in `forever list`
44 columns set <cols> Set all columns for the output in `forever list`
45 cleanlogs [CAREFUL] Deletes all historical forever log files
c073c47 @indexzero [api] First pass at "restart" functionality, not 100% yet
indexzero authored
46
a49483d @indexzero [doc] Updated README.md
indexzero authored
47 options:
c7ff2d9 @indexzero [doc] Update the help in the forever CLI and README.md
indexzero authored
48 -m MAX Only run the specified script MAX times
49 -l LOGFILE Logs the forever output to LOGFILE
50 -o OUTFILE Logs stdout from child script to OUTFILE
51 -e ERRFILE Logs stderr from child script to ERRFILE
52 -p PATH Base path for all forever related files (pid files, etc.)
53 -c COMMAND COMMAND to execute (defaults to node)
54 -a, --append Append logs
ee9f98b @mmalecki [doc fix] `--pidfile` is now called `--pidFile`
mmalecki authored
55 --pidFile The pid file
c7ff2d9 @indexzero [doc] Update the help in the forever CLI and README.md
indexzero authored
56 --sourceDir The source directory for which SCRIPT is relative to
57 --minUptime Minimum uptime (millis) for a script to not be considered "spinning"
58 --spinSleepTime Time to wait (millis) between launches of a spinning script.
2b8cf71 @mmalecki [doc] Add `--plain` option to README
mmalecki authored
59 --plain Disable command line colors
c7ff2d9 @indexzero [doc] Update the help in the forever CLI and README.md
indexzero authored
60 -d, --debug Forces forever to log debug output
61 -v, --verbose Turns on the verbose messages from Forever
62 -s, --silent Run the child script silencing stdout and stderr
7d7398b @indexzero [doc] Update README.md with watch file options
indexzero authored
63 -w, --watch Watch for file changes
592a1eb @fedot Added `watchDirectory` to the list of options in README (to fulfill #…
fedot authored
64 --watchDirectory Top-level directory to watch from
c7ff2d9 @indexzero [doc] Update the help in the forever CLI and README.md
indexzero authored
65 -h, --help You're staring at it
0d5a789 @indexzero [dist] Version bump.
indexzero authored
66
67 [Long Running Process]
68 The forever process will continue to run outputting log messages to the console.
69 ex. forever -o out.log -e err.log my-script.js
70
71 [Daemon]
72 The forever process will run as a daemon which will make the target process start
73 in the background. This is extremely useful for remote starting simple node.js scripts
74 without using nohup. It is recommended to run start with -o -l, & -e.
75 ex. forever start -l forever.log -o out.log -e err.log my-daemon.js
76 forever stop my-daemon.js
a49483d @indexzero [doc] Updated README.md
indexzero authored
77 ```
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
78
f27cdaa @indexzero [doc] Remove documenetation specific to `forever-monitor`
indexzero authored
79 There are [several examples][1] designed to test the fault tolerance of forever. Here's a simple usage example:
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
80
725d11d @indexzero [doc] Update README.md
indexzero authored
81 ``` bash
061d14f @mmalecki [fix doc] Fix README to match flatiron refactor
mmalecki authored
82 $ forever -m 5 examples/error-on-timer.js
725d11d @indexzero [doc] Update README.md
indexzero authored
83 ```
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
84
f27cdaa @indexzero [doc] Remove documenetation specific to `forever-monitor`
indexzero authored
85 ## Using forever module from node.js
86 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.
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
87
1dac9f4 @indexzero [doc] Updated README.md
indexzero authored
88 **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:
89
90 ``` js
91 forever.startServer(child);
92 ```
93
3d6018f @indexzero [doc] Update documentation on forever.load(). Fixes #72
indexzero authored
94 ### forever.load (config)
3ef90c1 @indexzero [doc] Add a little more color to documentation for `forever.load()`
indexzero authored
95 _Synchronously_ sets the specified configuration (config) for the forever module. There are two important options:
29bff87 @indexzero [doc] Updated formatting in README.md
indexzero authored
96
270d976 @ded preferGlobal
ded authored
97 * root: Directory to put all default forever log files
29bff87 @indexzero [doc] Updated formatting in README.md
indexzero authored
98 * pidPath: Directory to put all forever *.pid files
99
14c7aa8 @indexzero [api test bin doc] Added stop by script name feature. Improved the cl…
indexzero authored
100 ### forever.start (file, options)
101 Starts a script with forever.
102
103 ### forever.startDaemon (file, options)
104 Starts a script with forever as a daemon. WARNING: Will daemonize the current process.
105
29bff87 @indexzero [doc] Updated formatting in README.md
indexzero authored
106 ### forever.stop (index)
107 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.
108
109 ### forever.stopAll (format)
110 Stops all forever scripts currently running. This method returns an EventEmitter that raises the 'stopAll' event when complete.
111
1dac9f4 @indexzero [doc] Updated README.md
indexzero authored
112 ### forever.list (format, callback)
113 Returns a list of metadata objects about each process that is being run using forever. This method is synchronous and will return the list of metadata as such. Only processes which have invoked `forever.startServer()` will be available from `forever.list()`
29bff87 @indexzero [doc] Updated formatting in README.md
indexzero authored
114
e740fb6 @indexzero [doc] Update README.md for `forever logs *` commands
indexzero authored
115 ### forever.tail (target, [length,] callback)
116 Responds with the logs from the target script(s) from `tail`. If `length` is provided it is used as the `-n` parameter to `tail`.
117
cef3435 @indexzero [doc fix] Update `.cleanup` to `.cleanUp`. Fixes #199
indexzero authored
118 ### forever.cleanUp ()
57a5600 @indexzero [doc] Remove references to *.fvr files in README.md
indexzero authored
119 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.
29bff87 @indexzero [doc] Updated formatting in README.md
indexzero authored
120
3c7e4a7 @indexzero [dist doc] Version bump 0.3.1. Added CHANGELOG.md
indexzero authored
121 ### forever.cleanLogsSync (processes)
14c7aa8 @indexzero [api test bin doc] Added stop by script name feature. Improved the cl…
indexzero authored
122 Removes all log files from the root forever directory that do not belong to current running forever processes.
123
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
124 ## Run Tests
da44ad0 @indexzero [doc] Kill some ancient stuff in README.md
indexzero authored
125
126 ``` bash
725d11d @indexzero [doc] Update README.md
indexzero authored
127 $ npm test
a49483d @indexzero [doc] Updated README.md
indexzero authored
128 ```
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
129
f27cdaa @indexzero [doc] Remove documenetation specific to `forever-monitor`
indexzero authored
130 #### License: MIT
131 #### Author: [Charlie Robbins](http://github.com/indexzero)
132 #### Contributors: [Fedor Indutny](http://github.com/indutny), [James Halliday](http://substack.net/), [Charlie McConnell](http://github.com/avianflu), [Maciej Malecki](http://github.com/mmalecki)
00fc643 @indexzero [api bin doc test] Added stop, stopall, and list command line functio…
indexzero authored
133
f27cdaa @indexzero [doc] Remove documenetation specific to `forever-monitor`
indexzero authored
134 [0]: http://github.com/nodejitsu/forever-monitor
135 [1]: http://github.com/nodejitsu/forever-monitor/tree/master/examples
136 [2]: https://github.com/nodejitsu/forever/blob/master/lib/forever/cli.js
Something went wrong with that request. Please try again.