Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 241 lines (191 sloc) 10.132 kb
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
1 # forever
2
3 A simple CLI tool for ensuring that a given script runs continuously (i.e. forever).
4
5 ## Installation
6
7 ### Installing npm (node package manager)
725d11d Charlie Robbins [doc] Update README.md
indexzero authored
8 ``` bash
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
9 curl http://npmjs.org/install.sh | sh
a49483d Charlie Robbins [doc] Updated README.md
indexzero authored
10 ```
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
11
faacc0f Charlie Robbins [doc] Typo
indexzero authored
12 ### Installing forever
725d11d Charlie Robbins [doc] Update README.md
indexzero authored
13 ``` bash
14 $ [sudo] npm install forever -g
a49483d Charlie Robbins [doc] Updated README.md
indexzero authored
15 ```
725d11d Charlie Robbins [doc] Update README.md
indexzero authored
16
17 **Note:** If you are using forever _programatically_ you should not install it globally.
18
19 ``` bash
20 $ cd /path/to/your/project
21 $ [sudo] npm install forever
a49483d Charlie Robbins [doc] Updated README.md
indexzero authored
22 ```
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
23
270d976 Dustin Diaz preferGlobal
ded authored
24 ## Usage
25 There are two distinct ways to use forever: through the command line interface, or by requiring the forever module in your own code.
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
26
27 ### Using forever from the command line
28 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:
29
a49483d Charlie Robbins [doc] Updated README.md
indexzero authored
30 ```
7d7398b Charlie Robbins [doc] Update README.md with watch file options
indexzero authored
31 $ forever --help
061d14f Maciej Małecki [fix doc] Fix README to match flatiron refactor
mmalecki authored
32 usage: forever [options] [action] SCRIPT [script-options]
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
33
a49483d Charlie Robbins [doc] Updated README.md
indexzero authored
34 Monitors the script specified in the current process or as a daemon
0d5a789 Charlie Robbins [dist] Version bump.
indexzero authored
35
a49483d Charlie Robbins [doc] Updated README.md
indexzero authored
36 actions:
1dac9f4 Charlie Robbins [doc] Updated README.md
indexzero authored
37 start Start SCRIPT as a daemon
38 stop Stop the daemon SCRIPT
39 stopall Stop all running forever scripts
40 restart Restart the daemon SCRIPT
41 list List all running forever scripts
42 config Lists all forever user configuration
43 set <key> <val> Sets the specified forever config <key>
44 clear <key> Clears the specified forever config <key>
e740fb6 Charlie Robbins [doc] Update README.md for `forever logs *` commands
indexzero authored
45 logs Lists log files for all forever processes
46 logs <script|index> Tails the logs for <script|index>
1dac9f4 Charlie Robbins [doc] Updated README.md
indexzero authored
47 columns add <col> Adds the specified column to the output in `forever list`
48 columns rm <col> Removed the specified column from the output in `forever list`
49 columns set <cols> Set all columns for the output in `forever list`
50 cleanlogs [CAREFUL] Deletes all historical forever log files
c073c47 Charlie Robbins [api] First pass at "restart" functionality, not 100% yet
indexzero authored
51
a49483d Charlie Robbins [doc] Updated README.md
indexzero authored
52 options:
c7ff2d9 Charlie Robbins [doc] Update the help in the forever CLI and README.md
indexzero authored
53 -m MAX Only run the specified script MAX times
54 -l LOGFILE Logs the forever output to LOGFILE
55 -o OUTFILE Logs stdout from child script to OUTFILE
56 -e ERRFILE Logs stderr from child script to ERRFILE
57 -p PATH Base path for all forever related files (pid files, etc.)
58 -c COMMAND COMMAND to execute (defaults to node)
59 -a, --append Append logs
ee9f98b Maciej Małecki [doc fix] `--pidfile` is now called `--pidFile`
mmalecki authored
60 --pidFile The pid file
c7ff2d9 Charlie Robbins [doc] Update the help in the forever CLI and README.md
indexzero authored
61 --sourceDir The source directory for which SCRIPT is relative to
62 --minUptime Minimum uptime (millis) for a script to not be considered "spinning"
63 --spinSleepTime Time to wait (millis) between launches of a spinning script.
2b8cf71 Maciej Małecki [doc] Add `--plain` option to README
mmalecki authored
64 --plain Disable command line colors
c7ff2d9 Charlie Robbins [doc] Update the help in the forever CLI and README.md
indexzero authored
65 -d, --debug Forces forever to log debug output
66 -v, --verbose Turns on the verbose messages from Forever
67 -s, --silent Run the child script silencing stdout and stderr
7d7398b Charlie Robbins [doc] Update README.md with watch file options
indexzero authored
68 -w, --watch Watch for file changes
c7ff2d9 Charlie Robbins [doc] Update the help in the forever CLI and README.md
indexzero authored
69 -h, --help You're staring at it
0d5a789 Charlie Robbins [dist] Version bump.
indexzero authored
70
71 [Long Running Process]
72 The forever process will continue to run outputting log messages to the console.
73 ex. forever -o out.log -e err.log my-script.js
74
75 [Daemon]
76 The forever process will run as a daemon which will make the target process start
77 in the background. This is extremely useful for remote starting simple node.js scripts
78 without using nohup. It is recommended to run start with -o -l, & -e.
79 ex. forever start -l forever.log -o out.log -e err.log my-daemon.js
80 forever stop my-daemon.js
a49483d Charlie Robbins [doc] Updated README.md
indexzero authored
81 ```
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
82
079ca20 Charlie Robbins [doc] Small update to README.md
indexzero authored
83 There are several examples designed to test the fault tolerance of forever. Here's a simple usage example:
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
84
725d11d Charlie Robbins [doc] Update README.md
indexzero authored
85 ``` bash
061d14f Maciej Małecki [fix doc] Fix README to match flatiron refactor
mmalecki authored
86 $ forever -m 5 examples/error-on-timer.js
725d11d Charlie Robbins [doc] Update README.md
indexzero authored
87 ```
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
88
270d976 Dustin Diaz preferGlobal
ded authored
89 ### Using an instance of Forever from node.js
90 You can also use forever from inside your own node.js code.
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
91
725d11d Charlie Robbins [doc] Update README.md
indexzero authored
92 ``` js
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
93 var forever = require('forever');
270d976 Dustin Diaz preferGlobal
ded authored
94
dfb54be Charlie Robbins [api test doc] Remove deprecated `forever.Forever` from samples and test...
indexzero authored
95 var child = new (forever.Monitor)('your-filename.js', {
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
96 max: 3,
97 silent: true,
98 options: []
99 });
270d976 Dustin Diaz preferGlobal
ded authored
100
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
101 child.on('exit', this.callback);
0d5a789 Charlie Robbins [dist] Version bump.
indexzero authored
102 child.start();
a49483d Charlie Robbins [doc] Updated README.md
indexzero authored
103 ```
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
104
1dac9f4 Charlie Robbins [doc] Updated README.md
indexzero authored
105 **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:
106
107 ``` js
108 forever.startServer(child);
109 ```
110
57273ea James Halliday updated the readme with non-node usage and an example
substack authored
111 ### Spawning a non-node process
112 You can spawn non-node processes too. Either set the `command` key in the
113 `options` hash or pass in an `Array` in place of the `file` argument like this:
114
725d11d Charlie Robbins [doc] Update README.md
indexzero authored
115 ``` js
57273ea James Halliday updated the readme with non-node usage and an example
substack authored
116 var forever = require('forever');
117 var child = forever.start([ 'perl', '-le', 'print "moo"' ], {
118 max : 1,
119 silent : true
120 });
a49483d Charlie Robbins [doc] Updated README.md
indexzero authored
121 ```
57273ea James Halliday updated the readme with non-node usage and an example
substack authored
122
a4f1700 Charlie Robbins [api test doc dist] Version bump. Merged from donnerjack. Added ability ...
indexzero authored
123 ### Options available when using Forever in node.js
725d11d Charlie Robbins [doc] Update README.md
indexzero authored
124 There are several options that you should be aware of when using forever. Most of this configuration is optional.
a4f1700 Charlie Robbins [api test doc dist] Version bump. Merged from donnerjack. Added ability ...
indexzero authored
125
725d11d Charlie Robbins [doc] Update README.md
indexzero authored
126 ``` js
a4f1700 Charlie Robbins [api test doc dist] Version bump. Merged from donnerjack. Added ability ...
indexzero authored
127 {
725d11d Charlie Robbins [doc] Update README.md
indexzero authored
128 //
129 // Basic configuration options
130 //
131 'silent': false, // Silences the output from stdout and stderr in the parent process
270d976 Dustin Diaz preferGlobal
ded authored
132 'forever': true, // Indicates that this script should run forever
abed353 Charlie Robbins [doc] Updated README.md with newer options and events
indexzero authored
133 'uid': 'your-UID' // Custom uid for this forever process. (default: autogen)
725d11d Charlie Robbins [doc] Update README.md
indexzero authored
134 'pidFile': 'path/to/a.pid', // Path to put pid information for the process(es) started
135 'max': 10, // Sets the maximum number of times a given script should run
e740fb6 Charlie Robbins [doc] Update README.md for `forever logs *` commands
indexzero authored
136 'killTree': true // Kills the entire child process tree on `exit`
725d11d Charlie Robbins [doc] Update README.md
indexzero authored
137
138 //
139 // These options control how quickly forever restarts a child process
140 // as well as when to kill a "spinning" process
141 //
142 'minUptime': 2000, // Minimum time a child process has to be up. Forever will 'exit' otherwise.
143 'spinSleepTime': 1000, // Interval between restarts if a child is spinning (i.e. alive < minUptime).
144
145 //
146 // Command to spawn as well as options and other vars
147 // (env, cwd, etc) to pass along
148 //
149 'command': 'perl', // Binary to run (default: 'node')
150 'options': ['foo','bar'], // Additional arguments to pass to the script,
151 'sourceDir': 'script/path' // Directory that the source script is in
152
153 //
7d7398b Charlie Robbins [doc] Update README.md with watch file options
indexzero authored
154 // Options for restarting on watched files.
155 //
156 'watch': false // Value indicating if we should watch files.
157 'watchIgnoreDotFiles': null // Dot files we should read to ignore ('.foreverignore', etc).
158 'watchIgnorePatterns': null // Ignore patterns to use when watching files.
159 'watchDirectory': null // Top-level directory to watch from.
160
161 //
725d11d Charlie Robbins [doc] Update README.md
indexzero authored
162 // All or nothing options passed along to `child_process.spawn`.
163 //
abed353 Charlie Robbins [doc] Updated README.md with newer options and events
indexzero authored
164 'spawnWith': {
725d11d Charlie Robbins [doc] Update README.md
indexzero authored
165 env: process.env, // Information passed along to the child process
166 customFds: [-1, -1, -1], // that forever spawns.
abed353 Charlie Robbins [doc] Updated README.md with newer options and events
indexzero authored
167 setsid: false
725d11d Charlie Robbins [doc] Update README.md
indexzero authored
168 },
169
170 //
171 // More specific options to pass along to `child_process.spawn` which
172 // will override anything passed to the `spawnWith` option
173 //
174 'env': { 'ADDITIONAL': 'CHILD ENV VARS' }
175 'cwd': '/path/to/child/working/directory'
176
177 //
178 // Log files and associated logging options for this instance
179 //
180 'logFile': 'path/to/file', // Path to log output from forever process (when daemonized)
181 'outFile': 'path/to/file', // Path to log output from child stdout
182 'errFile': 'path/to/file' // Path to log output from child stderr
a4f1700 Charlie Robbins [api test doc dist] Version bump. Merged from donnerjack. Added ability ...
indexzero authored
183 }
a49483d Charlie Robbins [doc] Updated README.md
indexzero authored
184 ```
a4f1700 Charlie Robbins [api test doc dist] Version bump. Merged from donnerjack. Added ability ...
indexzero authored
185
00fc643 Charlie Robbins [api bin doc test] Added stop, stopall, and list command line functional...
indexzero authored
186 ### Events available when using an instance of Forever in node.js
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
187 Each forever object is an instance of the node.js core EventEmitter. There are several core events that you can listen for:
188
8a50cf6 Charlie Robbins [doc] Minor updates to README.md
indexzero authored
189 * **error** _[err]:_ Raised when an error occurs
190 * **start** _[process, data]:_ Raised when the target script is first started.
191 * **stop** _[process]:_ Raised when the target script is stopped by the user
192 * **restart** _[forever]:_ Raised each time the target script is restarted
193 * **exit** _[forever]:_ Raised when the target script actually exits (permenantly).
194 * **stdout** _[data]:_ Raised when data is received from the child process' stdout
195 * **stderr** _[data]:_ Raised when data is received from the child process' stderr
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
196
29bff87 Charlie Robbins [doc] Updated formatting in README.md
indexzero authored
197 ## Using forever module from node.js
a49483d Charlie Robbins [doc] Updated README.md
indexzero authored
198 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.
29bff87 Charlie Robbins [doc] Updated formatting in README.md
indexzero authored
199
3d6018f Charlie Robbins [doc] Update documentation on forever.load(). Fixes #72
indexzero authored
200 ### forever.load (config)
3ef90c1 Charlie Robbins [doc] Add a little more color to documentation for `forever.load()`
indexzero authored
201 _Synchronously_ sets the specified configuration (config) for the forever module. There are two important options:
29bff87 Charlie Robbins [doc] Updated formatting in README.md
indexzero authored
202
270d976 Dustin Diaz preferGlobal
ded authored
203 * root: Directory to put all default forever log files
29bff87 Charlie Robbins [doc] Updated formatting in README.md
indexzero authored
204 * pidPath: Directory to put all forever *.pid files
205
14c7aa8 Charlie Robbins [api test bin doc] Added stop by script name feature. Improved the clean...
indexzero authored
206 ### forever.start (file, options)
207 Starts a script with forever.
208
209 ### forever.startDaemon (file, options)
210 Starts a script with forever as a daemon. WARNING: Will daemonize the current process.
211
29bff87 Charlie Robbins [doc] Updated formatting in README.md
indexzero authored
212 ### forever.stop (index)
213 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.
214
215 ### forever.stopAll (format)
216 Stops all forever scripts currently running. This method returns an EventEmitter that raises the 'stopAll' event when complete.
217
1dac9f4 Charlie Robbins [doc] Updated README.md
indexzero authored
218 ### forever.list (format, callback)
219 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 Charlie Robbins [doc] Updated formatting in README.md
indexzero authored
220
e740fb6 Charlie Robbins [doc] Update README.md for `forever logs *` commands
indexzero authored
221 ### forever.tail (target, [length,] callback)
222 Responds with the logs from the target script(s) from `tail`. If `length` is provided it is used as the `-n` parameter to `tail`.
223
cef3435 Charlie Robbins [doc fix] Update `.cleanup` to `.cleanUp`. Fixes #199
indexzero authored
224 ### forever.cleanUp ()
57a5600 Charlie Robbins [doc] Remove references to *.fvr files in README.md
indexzero authored
225 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 Charlie Robbins [doc] Updated formatting in README.md
indexzero authored
226
3c7e4a7 Charlie Robbins [dist doc] Version bump 0.3.1. Added CHANGELOG.md
indexzero authored
227 ### forever.cleanLogsSync (processes)
14c7aa8 Charlie Robbins [api test bin doc] Added stop by script name feature. Improved the clean...
indexzero authored
228 Removes all log files from the root forever directory that do not belong to current running forever processes.
229
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
230 ## Run Tests
da44ad0 Charlie Robbins [doc] Kill some ancient stuff in README.md
indexzero authored
231
232 ``` bash
725d11d Charlie Robbins [doc] Update README.md
indexzero authored
233 $ npm test
a49483d Charlie Robbins [doc] Updated README.md
indexzero authored
234 ```
9f08ad1 Charlie Robbins [api dist doc] Updated docs, package.json and small options handling
indexzero authored
235
a49483d Charlie Robbins [doc] Updated README.md
indexzero authored
236 #### Author: [Charlie Robbins][0]
14c7aa8 Charlie Robbins [api test bin doc] Added stop by script name feature. Improved the clean...
indexzero authored
237 #### Contributors: [Fedor Indutny](http://github.com/donnerjack13589), [James Halliday](http://substack.net/)
00fc643 Charlie Robbins [api bin doc test] Added stop, stopall, and list command line functional...
indexzero authored
238
239 [0]: http://nodejitsu.com
fc4dec5 Louis Galipeau Fixed broken link, replaced indexzero with nodejitsu in url.
muloka authored
240 [1]: https://github.com/nodejitsu/forever/blob/master/lib/forever/cli.js
Something went wrong with that request. Please try again.