Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 241 lines (191 sloc) 10.132 kB
9f08ad1 @indexzero [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 @indexzero [doc] Update README.md
indexzero authored
8 ``` bash
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
9 curl http://npmjs.org/install.sh | sh
a49483d @indexzero [doc] Updated README.md
indexzero authored
10 ```
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
11
faacc0f @indexzero [doc] Typo
indexzero authored
12 ### Installing forever
725d11d @indexzero [doc] Update README.md
indexzero authored
13 ``` bash
14 $ [sudo] npm install forever -g
a49483d @indexzero [doc] Updated README.md
indexzero authored
15 ```
725d11d @indexzero [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 @indexzero [doc] Updated README.md
indexzero authored
22 ```
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
23
270d976 @ded 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 @indexzero [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 @indexzero [doc] Updated README.md
indexzero authored
30 ```
7d7398b @indexzero [doc] Update README.md with watch file options
indexzero authored
31 $ forever --help
061d14f @mmalecki [fix doc] Fix README to match flatiron refactor
mmalecki authored
32 usage: forever [options] [action] SCRIPT [script-options]
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
33
a49483d @indexzero [doc] Updated README.md
indexzero authored
34 Monitors the script specified in the current process or as a daemon
0d5a789 @indexzero [dist] Version bump.
indexzero authored
35
a49483d @indexzero [doc] Updated README.md
indexzero authored
36 actions:
1dac9f4 @indexzero [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 @indexzero [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 @indexzero [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 @indexzero [api] First pass at "restart" functionality, not 100% yet
indexzero authored
51
a49483d @indexzero [doc] Updated README.md
indexzero authored
52 options:
c7ff2d9 @indexzero [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 @mmalecki [doc fix] `--pidfile` is now called `--pidFile`
mmalecki authored
60 --pidFile The pid file
c7ff2d9 @indexzero [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 @mmalecki [doc] Add `--plain` option to README
mmalecki authored
64 --plain Disable command line colors
c7ff2d9 @indexzero [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 @indexzero [doc] Update README.md with watch file options
indexzero authored
68 -w, --watch Watch for file changes
c7ff2d9 @indexzero [doc] Update the help in the forever CLI and README.md
indexzero authored
69 -h, --help You're staring at it
0d5a789 @indexzero [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 @indexzero [doc] Updated README.md
indexzero authored
81 ```
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
82
079ca20 @indexzero [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 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
84
725d11d @indexzero [doc] Update README.md
indexzero authored
85 ``` bash
061d14f @mmalecki [fix doc] Fix README to match flatiron refactor
mmalecki authored
86 $ forever -m 5 examples/error-on-timer.js
725d11d @indexzero [doc] Update README.md
indexzero authored
87 ```
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
88
270d976 @ded 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 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
91
725d11d @indexzero [doc] Update README.md
indexzero authored
92 ``` js
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
93 var forever = require('forever');
270d976 @ded preferGlobal
ded authored
94
dfb54be @indexzero [api test doc] Remove deprecated `forever.Forever` from samples and t…
indexzero authored
95 var child = new (forever.Monitor)('your-filename.js', {
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
96 max: 3,
97 silent: true,
98 options: []
99 });
270d976 @ded preferGlobal
ded authored
100
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
101 child.on('exit', this.callback);
0d5a789 @indexzero [dist] Version bump.
indexzero authored
102 child.start();
a49483d @indexzero [doc] Updated README.md
indexzero authored
103 ```
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
104
1dac9f4 @indexzero [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 @substack 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 @indexzero [doc] Update README.md
indexzero authored
115 ``` js
57273ea @substack 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 @indexzero [doc] Updated README.md
indexzero authored
121 ```
57273ea @substack updated the readme with non-node usage and an example
substack authored
122
a4f1700 @indexzero [api test doc dist] Version bump. Merged from donnerjack. Added abili…
indexzero authored
123 ### Options available when using Forever in node.js
725d11d @indexzero [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 @indexzero [api test doc dist] Version bump. Merged from donnerjack. Added abili…
indexzero authored
125
725d11d @indexzero [doc] Update README.md
indexzero authored
126 ``` js
a4f1700 @indexzero [api test doc dist] Version bump. Merged from donnerjack. Added abili…
indexzero authored
127 {
725d11d @indexzero [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 @ded preferGlobal
ded authored
132 'forever': true, // Indicates that this script should run forever
abed353 @indexzero [doc] Updated README.md with newer options and events
indexzero authored
133 'uid': 'your-UID' // Custom uid for this forever process. (default: autogen)
725d11d @indexzero [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 @indexzero [doc] Update README.md for `forever logs *` commands
indexzero authored
136 'killTree': true // Kills the entire child process tree on `exit`
725d11d @indexzero [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 @indexzero [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 @indexzero [doc] Update README.md
indexzero authored
162 // All or nothing options passed along to `child_process.spawn`.
163 //
abed353 @indexzero [doc] Updated README.md with newer options and events
indexzero authored
164 'spawnWith': {
725d11d @indexzero [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 @indexzero [doc] Updated README.md with newer options and events
indexzero authored
167 setsid: false
725d11d @indexzero [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 @indexzero [api test doc dist] Version bump. Merged from donnerjack. Added abili…
indexzero authored
183 }
a49483d @indexzero [doc] Updated README.md
indexzero authored
184 ```
a4f1700 @indexzero [api test doc dist] Version bump. Merged from donnerjack. Added abili…
indexzero authored
185
00fc643 @indexzero [api bin doc test] Added stop, stopall, and list command line functio…
indexzero authored
186 ### Events available when using an instance of Forever in node.js
9f08ad1 @indexzero [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 @indexzero [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 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
196
29bff87 @indexzero [doc] Updated formatting in README.md
indexzero authored
197 ## Using forever module from node.js
a49483d @indexzero [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 @indexzero [doc] Updated formatting in README.md
indexzero authored
199
3d6018f @indexzero [doc] Update documentation on forever.load(). Fixes #72
indexzero authored
200 ### forever.load (config)
3ef90c1 @indexzero [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 @indexzero [doc] Updated formatting in README.md
indexzero authored
202
270d976 @ded preferGlobal
ded authored
203 * root: Directory to put all default forever log files
29bff87 @indexzero [doc] Updated formatting in README.md
indexzero authored
204 * pidPath: Directory to put all forever *.pid files
205
14c7aa8 @indexzero [api test bin doc] Added stop by script name feature. Improved the cl…
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 @indexzero [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 @indexzero [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 @indexzero [doc] Updated formatting in README.md
indexzero authored
220
e740fb6 @indexzero [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 @indexzero [doc fix] Update `.cleanup` to `.cleanUp`. Fixes #199
indexzero authored
224 ### forever.cleanUp ()
57a5600 @indexzero [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 @indexzero [doc] Updated formatting in README.md
indexzero authored
226
3c7e4a7 @indexzero [dist doc] Version bump 0.3.1. Added CHANGELOG.md
indexzero authored
227 ### forever.cleanLogsSync (processes)
14c7aa8 @indexzero [api test bin doc] Added stop by script name feature. Improved the cl…
indexzero authored
228 Removes all log files from the root forever directory that do not belong to current running forever processes.
229
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
230 ## Run Tests
da44ad0 @indexzero [doc] Kill some ancient stuff in README.md
indexzero authored
231
232 ``` bash
725d11d @indexzero [doc] Update README.md
indexzero authored
233 $ npm test
a49483d @indexzero [doc] Updated README.md
indexzero authored
234 ```
9f08ad1 @indexzero [api dist doc] Updated docs, package.json and small options handling
indexzero authored
235
a49483d @indexzero [doc] Updated README.md
indexzero authored
236 #### Author: [Charlie Robbins][0]
14c7aa8 @indexzero [api test bin doc] Added stop by script name feature. Improved the cl…
indexzero authored
237 #### Contributors: [Fedor Indutny](http://github.com/donnerjack13589), [James Halliday](http://substack.net/)
00fc643 @indexzero [api bin doc test] Added stop, stopall, and list command line functio…
indexzero authored
238
239 [0]: http://nodejitsu.com
fc4dec5 @muloka 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.