FOREMAN(1)

📦
version 0.90.0 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 FOREMAN(1) — the Foreman Manual, but make it a group chat 💖

okay bestie, sit down, hydrate, and let me tell you about foreman — the little command that manages your Procfile-based applications. the whole vibe is: we hide all the Procfile-format drama from you, so you can either run your app directly or export it into some other process management format. literally that's the entire personality. ✨

✨ SYNOPSIS ✨

foreman start [process]
foreman run <command>
foreman export <format> [location]

that's it. three whole modes. iconic behavior honestly. 💅

🌸 DESCRIPTION 🌸

So. 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.

that's the pitch. that's the whole pitch. and it ate. 🫶

🔥 RUNNING 🔥

foreman start is what you use to run your application directly from the command line. no middleman, no ceremony, just vibes and processes.

  • 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. just the one. she's picky like that.

The following options control how the application is run:

  • -m, --formation — 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.
ok so that last one? SIGKILL? that's the "no more mr. nice guy" signal. after your timeout runs out she stops asking politely. 😭

And then there's foreman run — that one is used to run one-off commands using the same environment as your defined processes. same env, no commitment. 💖

🦋 EXPORTING 🦋

foreman export is used to export your application to another process management format. she's helping you move out and get your own place. 🧚

A location to export can be passed as an argument. This argument may be either required or optional depending on the export format. (iykyk — check your format's docs, bestie.)

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.
  • -m, --formation — 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. the everywhere-everything options. 🌈

  • -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

seven of them. a whole little menu. pick your fighter. ⭐

💜 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 -----

look at that. a whole chunk. she did that. 💅

🌟 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

The special environment variables $PORT and $PS are available within the Procfile. $PORT is the port selected for that process. $PS is the name of the process for the line.

The $PORT value starts as the base port as specified by -p, then increments by 100 for each new process line. Multiple instances of the same process are assigned $PORT values that increment by 1.

no cap, that +100 vs +1 distinction trips people up ALL the time. write it down. 🫶

🌈 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:

formation: alpha=0,bravo=1
port: 15000

so like formation: not -m, okay? long names only. she's specific. 💖

🔥 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 -m all=1,worker=0

that last one is the classic. worker=0? she said not today. 😭✨

Foreman is Copyright (C) 2010 David Dollar http://daviddollar.org

ok that's the whole page bestie, you're officially a foreman girlie now 💅🦋✨

this was Foreman 0.90.0, from July 2025, and that's on periodt. 🎀 go run your processes, queen 👑

📦 where this page comes from