NAME¶
foreman - manage Procfile-based applications
SYNOPSIS¶
foreman start [process]
foreman run <command>
foreman export <format> [location]
DESCRIPTION¶
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.
RUNNING¶
foreman start is used to run your application directly from the command
line.
If no additional parameters are passed, foreman will run one instance of each
type of process defined in your Procfile.
If a parameter is passed, foreman will run one instance of the specified
application type.
The following options control how the application is run:
- -c, --concurrency
- Specify the number of each process type to run. The value passed in should
be in the format process=num,process=num
- -e, --env
- Specify one or more .env files to load
- -f, --procfile
- Specify an alternate Procfile to load, implies -d at the Procfile
root.
- -p, --port
- Specify which port to use as the base for this application. Should be a
multiple of 1000.
- -t, --timeout
- Specify the amount of time (in seconds) processes have to shutdown
gracefully before receiving a SIGKILL, defaults to 5.
foreman run is used to run one-off commands using the same environment as
your defined processes.
EXPORTING¶
foreman export is used to export your application to another process
management format.
An location to export can be passed as an argument. This argument may be either
required or optional depending on the export format.
The following options control how the application is run:
- -a, --app
- Use this name rather than the application´s root directory name as
the name of the application when exporting.
- -c, --concurrency
- Specify the number of each process type to run. The value passed in should
be in the format process=num,process=num
- -l, --log
- Specify the directory to place process logs in.
- -p, --port
- Specify which port to use as the base for this application. Should be a
multiple of 1000.
- -t, --template
- Specify an alternate template to use for creating export files. See
https://github.com/ddollar/foreman/tree/master/data/export for
examples.
- -u, --user
- Specify the user the application should be run as. Defaults to the app
name
GLOBAL OPTIONS¶
These options control all modes of foreman´s operation.
- -d, --root
- Specify an alternate application root. This defaults to the directory
containing the Procfile.
- -e, --env
- Specify an alternate environment file. You can specify more than one file
by using: --env file1,file2.
- -f, --procfile
- Specify an alternate location for the application´s Procfile. This
file´s containing directory will be assumed to be the root
directory of the application.
foreman currently supports the following output formats:
- •
- bluepill
- •
- inittab
- •
- launchd
- •
- runit
- •
- supervisord
- •
- systemd
- •
- upstart
-
INITTAB EXPORT¶
Will export a chunk of inittab-compatible configuration:
-
-
# ----- foreman example processes -----
EX01:4:respawn:/bin/su - example -c ´PORT=5000 bundle exec thin start >> /var/log/web-1.log 2>&1´
EX02:4:respawn:/bin/su - example -c ´PORT=5100 bundle exec rake jobs:work >> /var/log/job-1.log 2>&1´
# ----- end foreman example processes -----
-
SYSTEMD EXPORT¶
Will create a series of systemd scripts in the location you specify. Scripts
will be structured to make the following commands valid:
systemctl start appname.target
systemctl stop appname-processname.target
systemctl restart appname-processname-3.service
UPSTART EXPORT¶
Will create a series of upstart scripts in the location you specify. Scripts
will be structured to make the following commands valid:
start appname
stop appname-processname
restart appname-processname-3
PROCFILE¶
A Procfile should contain both a name for the process and the command used to
run it.
-
-
web: bundle exec thin start
job: bundle exec rake jobs:work
-
A process name may contain letters, numbers and the underscore character. You
can validate your Procfile format using the
check command:
-
-
$ foreman check
-
ENVIRONMENT¶
If a
.env file exists in the current directory, the default environment
will be read from it. This file should contain key/value pairs, separated by
=, with one key/value pair per line.
-
-
FOO=bar
BAZ=qux
-
DEFAULT OPTIONS¶
If a
.foreman file exists in the current directory, default options will
be read from it. This file should be in YAML format with the long option name
as keys. Example:
-
-
concurrency: alpha=0,bravo=1
port: 15000
-
EXAMPLES¶
Start one instance of each process type, interleave the output on stdout:
-
-
$ foreman start
-
Export the application in upstart format:
-
-
$ foreman export upstart /etc/init
-
Run one process type from the application defined in a specific Procfile:
-
-
$ foreman start alpha -f ~/myapp/Procfile
-
Start all processes except the one named worker:
-
-
$ foreman start -c all=1,worker=0
-
COPYRIGHT¶
Foreman is Copyright (C) 2010 David Dollar
http://daviddollar.org
