Procfile support is one of our compatibility layers that makes Scalingo compatible with Heroku.

Definition

The Procfile is a way to define how the platform will try to start your containers. In this file, you can define all the different process you would like to run in your project from the same code base. It is commonly used to define how to start workers which will consume asynchronous jobs.

A Procfile is a text file using the YAML format describing how to start each type of container for your app. It has to be located at the root of your project. Environment variables will be interpolated.

web: bundle exec rails server -p $PORT -e $RAILS_ENV -b 0.0.0.0
worker: bundle exec sidekiq -e $RAILS_ENV

By default, when you first try to deploy your application, we’ll try to launch the web process. We try to determine it without your help, but in some cases it is required to define it, as in the previous example. If your application requires a Procfile and you haven’t defined it, your deployment will fail and a log entry will attest the lack of Procfile.

The standard syntax is:

<container type>: <command>

where:

• <container type> should contain letters and digits only.
• <command> can be any Bash command. It can include environment variables.

When you have more complex commands to run, don’t hesitate to write a short start script, for instance in bin/start.sh:

#!/bin/bash

if [ "$SOME_ENV" = "SOME_VALUE" ] ; then
  exec run_this_command -p $PORT
else
  exec run_that_other_command
fi

Then in your Procfile, directly call this script:

web: bash bin/start.sh

Postdeploy Hook

The Procfile is also the place to declare a post-deploy hook. More information here.

You can use a custom script if you only want to run the post-deploy hook in some situations, in the following case if the variable SOME_ENV equals SOME_VALUE:

#!/bin/bash

if [ "$SOME_ENV" = "SOME_VALUE" ] ; then
  exec postdeploy_command -p $PORT
else
  echo "Postdeploy hook disabled"
  exit 0
fi

Then modify the Procfile:

postdeploy: bash bin/postdeploy.sh

Removing a Container Type

If you have two container types declared in your Procfile web and a worker:

web: bundle exec rails server -p $PORT -e $RAILS_ENV -b 0.0.0.0
worker: bundle exec sidekiq -e $RAILS_ENV

But you eventually want to remove the worker container type. You first need to scale down to 0 the worker container. Then remove the line starting with worker in your Procfile and trigger a new deployment.

If you forget to scale down the amount of worker containers, you will see the following error message in your application logs:

2022-01-26 10:46:17.855295004 +0000 UTC [worker-1] Task 'worker' has not been found in your 'Procfile'

Using in development

To reduce the environment gap between the development and the production, it is important to execute the same processes in development and in any deployed environment.

To achieve this different tools exist. The most famous is foreman. A little ruby gem executing and displaying the output of all the processes defined in your Procfile.

└> cat Procfile
web: bin/project
worker: bin/project -worker

└> foreman start
17:52:56 web.1    | started with pid 10663
17:52:56 worker.1 | started with pid 10664
17:52:56 web.1    | 2014/12/01 17:52:56 Listen HTTP requests on :5000
17:52:56 worker.1 | 2014/12/01 17:52:56 Starting Asynchronous worker

To install it: gem install foreman

Alternatives to foreman:

• honcho
• goreman
• Overmind