Node Foreman
Node Foreman is a Node.js version of the popular
Foreman tool,
with a few Node specific changes.
Foreman is a manager for Procfile-based applications.
Its aim is to abstract away the details of the Procfile
format, and allow you to either run your application
directly or export it to some other process management format.
Install
Install the command line tool
npm install -g foreman
Get usage
nf --help
Deviations from the original Foreman
- Each worker has an additional automatic environment variable,
FOREMAN_WORKER_NAME
, that contains the process name and worker number.- example:
web.1
,worker.1
- example:
How to Contribute
I encourage anyone and everyone to help.
If you have a specific change in mind, open an issue; we can talk about it there.
If you would like to make a code change, go ahead.
Fork the repository, open a pull request.
Do this early, and talk about the change you want to make.
Maybe we can work together on it.
Refactor Refactor Refactor!
You are free to add features, or just help clean things up.
Usage
Node Foreman can be run with as little as nf start
, as long as npm start
has been defined.
For more complicated applications you will want to define a Procfile
for your various server
processes and an .env
file to pre-load environmental variables.
Your module directory should end up looking like the following:
Once your Procfile
is defined, run your application with nf start
:
Node Foreman always starts in the foreground and expects your applications
to do the same. If your processes exit, Node Foreman will assume an error
has occurred and shut your application down.
Instead of daemonizing, you should use nf export
to ready your application
for production.
For more information try any of the following:
$ nf --help
$ nf start --help
$ nf run --help
$ nf export --help
Procfile
The Procfile
format is a simple key : command
format:
web: node web_server.js
api: node api_server.js
log: node log_server.js
Each line should contain a separate process.
Environmental Variables
Create a .env
file to pre-load environmental variables with the format:
MYSQL_NAME=superman
MYSQL_PASS=cryptonite
The equivalent .env
file may alternatively be a valid JSON document:
{
"mysql":{
"name": "superman",
"pass": "cryptonite"
}
}
The above JSON document will be flattened into env variables by
concatenating the nested values with an underscore.
Environmental variables are passed in fully capitalized.
{
"mysql":{
"name": "superman", # => MYSQL_NAME=superman
"pass": "cryptonite" # => MYSQL_PASS=cryptonite
}
}
There is no need to specify which type of file you wish to use.
The PATH environment variable
The PATH
variable is given special treatment and is always read
from the environment that the nf
command has been executed from,
rather than your .env
file. To set a different PATH
execute
nf
with the PATH
variable set appropriately.
PATH=/opt/foo:/opt/bar:$PATH nf export
Best Practices
Generally you should not check your .env
file into version control.
The .env
file contain only parameters that depend on where the application
gets deployed. It should not contain anything related to how the application
is deployed.
For example, good candidates for the .env
file are MySQL connection information,
port bindings, and other passwords.
The Run Command
Tasks or commands that require the environment variables from the .env
file
can be initiated by using nf run <command>
.
Advanced Usage
Node Foreman lets you start multiple jobs of the same type:
$ nf start web=5
18:51:12: web.1