foreman

Start an application with the Procfile in the current directory

$ foreman start

$ foreman start [[-f|--procfile]] [Procfile]

$ foreman start [process]

$ foreman check

$ foreman run [command]

$ foreman start [[-m|--formation]] all=1,[worker]=0

foreman command [options] [arguments]

Common commands include:
foreman start [PROCESS]
foreman run COMMAND [ARGS]
foreman export FORMAT DIRECTORY
foreman check
foreman help [COMMAND]

--procfile path, -f path
    Specifies an alternative Procfile to load instead of the default ./Procfile.

--env path, -e path
    Specifies one or more .env files from which to load environment variables. Can be specified multiple times.

--port port, -p port
    Sets the base port for web processes (e.g., via the `PORT` environment variable), defaulting to 5000.

--concurrency spec, -c spec
    Specifies the number of processes to start for each process type (e.g., web=2,worker=1).

--root path, -r path
    Specifies the application's root directory, used to locate the Procfile and .env files.

--full-color, -F
    Forces full color output, even when output is redirected or piped.

--no-color, -N
    Disables color output from processes.

--index, -i
    Indexes processes with a suffix (e.g., web.1, web.2) for unique identification.

foreman is a command-line tool that facilitates the management of application process groups, primarily by reading definitions from a Procfile. A Procfile specifies various process types required by an application, such as web servers, background workers, or databases. When executed, foreman launches all defined processes concurrently, directing their standard output and error streams to the console. To enhance readability, each process's output is color-coded. A key feature is its default behavior: if any process defined in the Procfile terminates unexpectedly, foreman automatically shuts down all other running processes, ensuring a clean exit. This makes it exceptionally useful for orchestrating complex, multi-service applications during local development, providing a consistent way to start and monitor all application components. It also integrates with .env files for loading environment variables.

foreman is primarily designed for local development environments and is generally not recommended for production deployment without using its export functionality to generate system-specific service files (like Upstart or Systemd units). Its process monitoring is basic; it simply shuts down all processes if one fails, without advanced restart strategies. Managing output from many concurrent processes can be challenging without proper logging configuration.

foreman relies heavily on the Procfile, a simple text file typically located in the root directory of an application. This file defines the commands required to start each process type for the application. For example:
web: bundle exec rails s
worker: bundle exec sidekiq
Each line specifies a process type (e.g., 'web', 'worker') followed by a colon and the command to execute it.

foreman can automatically load environment variables from .env files. These files, usually named .env, .env.development, etc., contain key-value pairs that are loaded into the environment of the processes started by foreman. This provides a convenient way to manage configuration without hardcoding sensitive information or specific settings directly into the Procfile.

While primarily for development, foreman includes an export command that can generate configuration files for various process management systems. This allows for a more production-ready deployment of applications defined by a Procfile. Supported export formats include Upstart, Systemd, Bluepill, Runit, launchd, inittab, and Supervisord.

The foreman tool was inspired by Heroku's process model, which advocates for defining application processes in a Procfile. It was originally developed by David Dollar and is written in Ruby. Its popularity, particularly within the Ruby on Rails community, led to the creation of numerous cross-language implementations and alternatives, such as honcho (Python) and goreman (Go), aiming to replicate its simple yet powerful process management capabilities for local development across different technology stacks.

systemd(1), upstart(8), supervisord(1), docker-compose(1), pm2(1)