Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Procfile

A Procfile is a plain text file at the root of your repository (or, for an app built from a subdirectory, that directory) that names the process types your code can run. It’s supported for every framework, so it works whatever language your app is written in.

Format

One line per process type, <name>: <command>:

web: bundle exec puma -p $PORT
worker: bundle exec sidekiq
release: bin/rails db:migrate

web and worker are conventional names, matching the two kinds of app the platform runs, but a process type can be named anything — whichever name matches what the app it belongs to needs.

Which process an app runs

When a build produces more than one process type, each app built from it picks one to run. The platform decides, in order:

  1. process: in that app’s d2o-paas.yaml, if present;
  2. the app’s Process setting (--process in the CLI, the Process field in the dashboard — formerly called “Start command”), if set;
  3. the Procfile line whose name matches the app’s own name — an app named worker runs the worker: line automatically, with nothing to configure;
  4. web, if none of the above apply.

Name matching (step 3) is a convenience, not something you declare — an explicit process: or Process setting always wins over it.

Name matching applies to apps created from now on only. An app that already existed before this feature shipped keeps running whatever process it runs today, even if its name matches a Procfile line — so an existing worker app with a worker: line in its Procfile doesn’t silently switch what it runs. To opt such an app into name matching, clear its Process setting:

paas apps update worker --process "" -o acme -p shop -e production

The release process

A line named release: is special — it isn’t a process the platform keeps running. Instead, it runs once against each new version, before any instance of the app starts, exactly like the app’s Release command setting. See Release command for the full behavior: when it runs, what happens if it fails, and why it should be safe to run more than once.

The Procfile’s release: line takes precedence over the app’s Release command setting. If both are present, release: runs and the setting is ignored — the deployment timeline says so:

Your app's release command setting is ignored because the Procfile defines `release:`

This is the one behavior change for apps that already have both: previously the app setting won; now the Procfile does. To go back to using the app setting, remove the release: line from the Procfile.

Every language is supported

The Procfile is read for Ruby on Rails, Node.js, Python, Go and Rust apps (a Static Files site has no processes of its own). Python apps must have one: the Python build has no default start command, so a Python app without a Procfile fails to build. For the others you don’t need one if the framework already knows how to start your app (for example, a Rails app’s default web process); add one when your build produces more than one process type, or to name a release command.

Next steps