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.

EXPORT FORMATS

       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