David Dollar
162 lines
4.3 KiB
Markdown
162 lines
4.3 KiB
Markdown
foreman(1) -- manage Procfile-based applications
|
|
================================================
|
|
|
|
## SYNOPSIS
|
|
|
|
`foreman start [process]`<br>
|
|
`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`
|
|
|
|
* `-p`, `--port`:
|
|
Specify which port to use as the base for this application. Should be
|
|
a multiple of 1000.
|
|
|
|
## 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.
|
|
|
|
* `-u`, `--user`:
|
|
Specify the user the application should be run as. Defaults to the
|
|
app name
|
|
|
|
## OPTIONS
|
|
|
|
These options control all modes of foreman's operation.
|
|
|
|
* `-d`, `--directory`:
|
|
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.
|
|
|
|
## EXPORT FORMATS
|
|
|
|
foreman currently supports the following output formats:
|
|
|
|
* bluepill
|
|
|
|
* inittab
|
|
|
|
* runit
|
|
|
|
* 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 -----
|
|
|
|
## 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 amd 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 -p ~/myapp/Procfile
|
|
|
|
## COPYRIGHT
|
|
|
|
Foreman is Copyright (C) 2010 David Dollar <http://daviddollar.org>
|