1 | # Node Foreman [![Build Status](https://travis-ci.org/strongloop/node-foreman.svg)](https://travis-ci.org/strongloop/node-foreman)
|
2 |
|
3 | Node Foreman is a Node.js version of the popular
|
4 | [Foreman](http://ddollar.github.com/foreman/) tool,
|
5 | with a few Node specific changes.
|
6 |
|
7 | > Foreman is a manager for Procfile-based applications.
|
8 | > Its aim is to abstract away the details of the Procfile
|
9 | > format, and allow you to either run your application
|
10 | > directly or export it to some other process management format.
|
11 |
|
12 | ## Install
|
13 |
|
14 | Install the command line tool
|
15 |
|
16 | $ npm install -g foreman
|
17 |
|
18 | Get usage
|
19 |
|
20 | $ nf --help
|
21 |
|
22 | ## Deviations from the original Foreman
|
23 |
|
24 | * Each worker has an additional automatic environment variable,
|
25 | `FOREMAN_WORKER_NAME`, that contains the the process name and worker number.
|
26 | * example: `web.1`, `worker.1`
|
27 |
|
28 | ### How to Contribute
|
29 |
|
30 | I encourage anyone and everyone to help.
|
31 | If you have a specific change in mind, open an issue; we can talk about it there.
|
32 |
|
33 | If you would like to make a code change, go ahead.
|
34 | Fork the repository, open a pull request.
|
35 | Do this early, and talk about the change you want to make.
|
36 | Maybe we can work together on it.
|
37 |
|
38 | Refactor Refactor Refactor!
|
39 | You are free to add features, or just help clean things up.
|
40 |
|
41 | ## Usage
|
42 |
|
43 | Node Foreman can be run with as little as `nf start`, as long as `npm start` has been defined.
|
44 | For more complicated applications you will want to define a `Procfile` for your various server
|
45 | processes and and a `.env` file to preload environmental variables.
|
46 |
|
47 | Your module directory should end up looking like the following:
|
48 |
|
49 | ![List Foreman Directory](https://raw.github.com/strongloop/node-foreman/master/assets/foreman-ls.png)
|
50 |
|
51 | Once your Procfile is defined, run your application with `nf start`:
|
52 |
|
53 | ![Start Foreman](https://raw.github.com/strongloop/node-foreman/master/assets/foreman-start.png)
|
54 |
|
55 | Node Foreman _always_ starts in the foreground and expects your applications
|
56 | to do the same. If your processes exit, Node Foreman will assume an error
|
57 | has ocurred and shut your application down.
|
58 |
|
59 | Instead of daemonizing, you should use `nf export` to ready your application
|
60 | for production.
|
61 |
|
62 | For more information try any of the following:
|
63 |
|
64 | $ nf --help
|
65 | $ nf start --help
|
66 | $ nf run --help
|
67 | $ nf export --help
|
68 |
|
69 | ### Procfile
|
70 |
|
71 | The `Procfile` format is a simple `key : command` format:
|
72 |
|
73 | web: node web_server.js
|
74 | api: node api_server.js
|
75 | log: node log_server.js
|
76 |
|
77 | Each line should contain a separate process.
|
78 |
|
79 | ### Environmental Variables
|
80 |
|
81 | Create a `.env` file to pre-load environmental variables with the format:
|
82 |
|
83 | MYSQL_NAME=superman
|
84 | MYSQL_PASS=cryptonite
|
85 |
|
86 | The equivalent `.env` file may alternatively be a valid JSON document:
|
87 |
|
88 | {
|
89 | "mysql":{
|
90 | "name": "superman",
|
91 | "pass": "cryptonite"
|
92 | }
|
93 | }
|
94 |
|
95 | The above JSON document will be flattened into env variables by
|
96 | concatenating the nested values with an underscore.
|
97 | Environmental variables are passed in fully capitalized.
|
98 |
|
99 | {
|
100 | "mysql":{
|
101 | "name": "superman", # => MYSQL_NAME=superman
|
102 | "pass": "cryptonite" # => MYSQL_PASS=cryptonite
|
103 | }
|
104 | }
|
105 |
|
106 | There is no need to specify which type of file you wish to use.
|
107 |
|
108 | #### The PATH environment variable
|
109 |
|
110 | The `PATH` variable is given special treament and is always read
|
111 | from the environment that the `nf` command has been executed from,
|
112 | rather than a `.env` file. To set a different `PATH` execute
|
113 | `nf` with the `PATH` variable set appropriately.
|
114 |
|
115 | ```bash
|
116 | PATH=/opt/foo:/opt/bar:$PATH nf export
|
117 | ```
|
118 |
|
119 | #### Best Practices
|
120 |
|
121 | Generally you should not check your `.env` file into version control.
|
122 | The `.env` file contain _only_ parameters that depend on where the application
|
123 | gets deployed. It should not contain anything related to _how_ the application
|
124 | is deployed.
|
125 |
|
126 | For example, good candidates for the `.env` file are MySQL connection information,
|
127 | port bindings, and other passwords.
|
128 |
|
129 | ### The Run Command
|
130 |
|
131 | Tasks or commands that require the environment variables from the `.env` file
|
132 | can be initiated by using `nf run <command>`.
|
133 |
|
134 |
|
135 | ### Advanced Usage
|
136 |
|
137 | Node Foreman lets you start multiple jobs of the same type:
|
138 |
|
139 | $ nf start web=5
|
140 |
|
141 | 18:51:12: web.1 | Web Server started listening on 0.0.0.0:5000
|
142 | 18:51:12: web.2 | Web Server started listening on 0.0.0.0:5001
|
143 | 18:51:12: web.3 | Web Server started listening on 0.0.0.0:5002
|
144 | 18:51:12: web.4 | Web Server started listening on 0.0.0.0:5003
|
145 | 18:51:12: web.5 | Web Server started listening on 0.0.0.0:5004
|
146 |
|
147 | Each job will be started as its own process, receiving a different `PORT`
|
148 | environmental variable.
|
149 | The port number for processes of the same type will be offset by 1.
|
150 | The port number for processes of different types will be offset by 100.
|
151 |
|
152 | $ nf start web=2,api=2
|
153 |
|
154 | 18:51:12: web.1 | Web Server started listening on 0.0.0.0:5000
|
155 | 18:51:12: web.2 | Web Server started listening on 0.0.0.0:5001
|
156 | 18:51:12: api.1 | Api Server started listening on 0.0.0.0:5100
|
157 | 18:51:12: api.2 | Api Server started listening on 0.0.0.0:5101
|
158 |
|
159 | ## Export to Production
|
160 |
|
161 | Node Foreman is designed to be in a development environment,
|
162 | however it can export an Upstart job for use in production.
|
163 | The Upstart file has _no_ dependency on Node Foreman.
|
164 |
|
165 | $ nf export
|
166 | Loaded ENV .env File as JSON Format
|
167 | Wrote : ./foreman-web-1.conf
|
168 | Wrote : ./foreman-web.conf
|
169 | Wrote : ./foreman-api-1.conf
|
170 | Wrote : ./foreman-api.conf
|
171 | Wrote : ./foreman-log-1.conf
|
172 | Wrote : ./foreman-log.conf
|
173 | Wrote : ./foreman.conf
|
174 |
|
175 | You can inspect your upstart files before placing them in the right
|
176 | directory, or have foreman do it for you:
|
177 |
|
178 | $ sudo nf export -o /etc/init
|
179 | Loaded ENV .env File as JSON Format
|
180 | Wrote : /etc/init/foreman-api-1.conf
|
181 | Wrote : /etc/init/foreman-web.conf
|
182 | Wrote : /etc/init/foreman-api.conf
|
183 | Wrote : /etc/init/foreman-log.conf
|
184 | Wrote : /etc/init/foreman-log-1.conf
|
185 | Wrote : /etc/init/foreman-web-1.conf
|
186 | Wrote : /etc/init/foreman.conf
|
187 |
|
188 | Start and stop your jobs with
|
189 |
|
190 | $ sudo start foreman
|
191 | $ sudo stop foreman
|
192 |
|
193 | The export will occur with whatever environmental variables are
|
194 | listed in the .env file.
|
195 |
|
196 | ### Systemd Support
|
197 |
|
198 | _This section is beta_
|
199 |
|
200 | Optionally specify a type `-t systemd` during export for [systemd](http://www.freedesktop.org/wiki/Software/systemd) support.
|
201 |
|
202 | ### Supervisord Support
|
203 |
|
204 | You can also use a type `-t supervisord` during export for [supervisord](http://www.supervisord.org) support.
|
205 |
|
206 | This will generate a `APP.conf` file grouping the application processes and a `APP-PROCESS-N.conf` file for each process.
|
207 |
|
208 | $ nf export --type supervisord
|
209 | Loaded ENV .env File as JSON Format
|
210 | Wrote : ./foreman-web-1.conf
|
211 | Wrote : ./foreman-api-1.conf
|
212 | Wrote : ./foreman-log-1.conf
|
213 | Wrote : ./foreman.conf
|
214 |
|
215 | You can start / stop / restart individual processes.
|
216 |
|
217 | $ sudo supervisorctl start 'foreman:foreman-web-1'
|
218 | $ sudo supervisorctl stop 'foreman:foreman-web-1'
|
219 | $ sudo supervisorctl restart 'foreman:foreman-web-1'
|
220 |
|
221 | Or the entire group of processes
|
222 |
|
223 | $ sudo supervisorctl start 'foreman:*'
|
224 | $ sudo supervisorctl stop 'foreman:*'
|
225 | $ sudo supervisorctl restart 'foreman:*'
|
226 |
|
227 | ### Advanced Exports
|
228 |
|
229 | You can specify the type and number of processes exported using
|
230 | the `type=num` syntax:
|
231 |
|
232 | $ nf export web=2,api=2
|
233 |
|
234 | Use `-u <USER>` to have the exported job run as `USER`.
|
235 | Note that if you need to bind to privileged ports, you _must_
|
236 | start as `root`. In such a case, we advise you to drop user
|
237 | permissions after binding.
|
238 |
|
239 | If you want to call your upstart job something other than foreman,
|
240 | use `-a <JOBNAME>` and manage your jobs with `sudo start <JOBNAME>`.
|
241 |
|
242 | ## Reverse Proxy
|
243 |
|
244 | Node.js processes are supposed to be stateless.
|
245 | Application scale by starting multiple processes that either share a socket,
|
246 | or sit behind a load balancer.
|
247 | Node Foreman can help you test the parallel capabilities of your application
|
248 | by spawning multiple processes behind a round-robin proxy automatically.
|
249 |
|
250 | $ nf start -x 8888 web=5
|
251 | [OKAY] Starting Proxy Server 8888 -> 5000-5004
|
252 |
|
253 | Access your application from port `8888` and the connections will be balanced
|
254 | across the servers started from ports `5000` - `5004`.
|
255 |
|
256 | If your application gets its port number from `process.env.PORT` the proxy
|
257 | setup will ocurr automatically.
|
258 |
|
259 | ### Multiple Reverse Proxies
|
260 |
|
261 | If you have multiple processes in your `Procfile` you can start multiple proxies.
|
262 |
|
263 | $ nf start -x 8888,8080,9090
|
264 |
|
265 | This will start 3 separate proxies and bind each to a separate process group.
|
266 | Proxies are bound based on their order specified, their order in the Procfile,
|
267 | or by their order on the command line.
|
268 |
|
269 | $ nf start -x 8888,9999 web,api
|
270 |
|
271 | ### Privileged Ports
|
272 |
|
273 | Node Foreman disallows applications from starting on privileged ports.
|
274 | It does however allow proxies to be bound to lower ports, such as port 80.
|
275 |
|
276 | If you require access to a privileged port, start Node Foreman with `sudo`:
|
277 |
|
278 | $ sudo nf start -x 80 web=5
|
279 | [OKAY] Starting Proxy Server 80 -> 5000-5004
|
280 |
|
281 | Your application will then be accessible via port 80.
|
282 |
|
283 | Your applications will _still_ be started in user space, and the proxy will
|
284 | drop its privileges after binding to the privileged port.
|
285 |
|
286 | ## Forward Proxy
|
287 |
|
288 | Local development and testing has huge advantages,
|
289 | but sometimes one needs to test web applications agains their real-world domain name.
|
290 | Editing `/etc/hosts` is a pain however, and error prone.
|
291 |
|
292 | Node Foreman can start up an HTTP forward proxy which your browser can route requests through.
|
293 | The forward proxy will intercept requests based on domain name, and route them to the local application.
|
294 |
|
295 | $ nf start -f 9999 -h nodefly.com
|
296 | [OKAY] Forward Proxy Started in Port 9999
|
297 | [OKAY] Intercepting requests to nodefly.com through forward proxy
|
298 |
|
299 | A forward proxy is useful when testing OAuth, or other external services with application callbacks.
|
300 |
|
301 | For users with Google Chrome, this can be paired with [Proxy Switch Sharp](http://switchy.samabox.com/) for great results.
|