Process Types and the Procfile
Last updated 15 February 2018
Table of Contents
A Procfile is a mechanism for declaring what commands are run by your application’s dynos on the Heroku platform. It follows the process model. You can use a Procfile to declare various process types, such as multiple types of workers, a singleton process like a clock, or a consumer of the Twitter streaming API.
Every dyno in your application will belong to one of the process types, and will begin executing by running the command associated with that process type.
Procfile naming and location
A Procfile is a file named
Procfile. It should be named
Procfile exactly, and not anything else. For example,
Procfile.txt is not valid. The file should be a simple text file.
The file must be placed in the root directory of your application. It will not function if placed in a subdirectory.
Process types as templates
A Procfile contains a number of process type declarations, each on a new line. Each process type is a declaration of a command that is executed when a dyno of that process type is started.
For example, if a
web process type is declared, then when a dyno of this type is started, the command associated with the
web process type, will be executed. This could mean starting a web server, for example.
As an example, a Rails application might have the following process type:
web: bundle exec rails server -p $PORT
A Clojure app’s
web process type might look something like this:
web: lein run -m demo.web $PORT
You can reference other environment variables populated by Heroku, most usefully the $PORT variable, in the command.
An executable Java JAR file, such as when using Spring Boot:
web: java -jar target/myapp-1.0.0.jar
For many apps, these defaults will be sufficient. For more sophisticated apps, and to adhere to the recommended approach of more explicitly declaring of your application’s required runtime processes, you may wish to define your process types. For example, Rails applications are supplied with an additional process type of this sort:
worker: bundle exec rake jobs:work
Declaring process types
Process types are declared via a file named
Procfile placed in the root directory of your app. Its format is one process type per line, with each line containing:
<process type>: <command>
The syntax is defined as:
<process type> – an alphanumeric string, is a name for your command, such as
<command> – a command line to launch the process, such as
web process type is special as it’s the only process type that will receive HTTP traffic from Heroku’s routers. Other process types can be named arbitrarily.
It’s important when developing and debugging an application that the local development environment is executed in the same manner as the remote environments. This ensures that incompatibilities and hard to find bugs are caught before deploying to production and treats the application as a holistic unit instead of a series of individual commands working independently.
Use the Heroku Local command-line tool to run your app locally. For more information see the Heroku Local article.
Deploying to Heroku
Procfile is not necessary to deploy apps written in most languages supported by Heroku. The platform automatically detects the language, and creates a default
web process type to boot the application server.
Creating an explicit
Procfile is recommended for greater control and flexibility over your app.
For Heroku to use your Procfile, add the
Procfile to the root directory of your application, then push to Heroku:
$ git add . $ git commit -m "Procfile" $ git push heroku master ... -----> Procfile declares process types: web, worker Compiled slug size is 10.4MB -----> Launching... done http://strong-stone-297.herokuapp.com deployed to Heroku To email@example.com:strong-stone-297.git * [new branch] master -> master
heroku ps to determine the number of dynos that are executing. The list indicates the process type in the left column, and the command corresponding to that process type in the right column:
$ heroku ps === web: `bundle exec rails server -p $PORT` web.1: up for 2m
heroku logs to view an aggregated list of log messages from all dynos across all process types.
$ heroku logs 2011-04-26T01:24:20-07:00 heroku[slugc]: Slug compilation finished 2011-04-26T01:24:22+00:00 heroku[web.1]: Running process with command: `bundle exec rails server mongrel -p 46999` 2011-04-25T18:24:22-07:00 heroku[web.1]: State changed from created to starting 2011-04-25T18:24:29-07:00 heroku[web.1]: State changed from starting to up 2011-04-26T01:24:29+00:00 app[web.1]: => Booting Mongrel 2011-04-26T01:24:29+00:00 app[web.1]: => Rails 3.0.5 application starting in production on http://0.0.0.0:46999 2011-04-26T01:24:29+00:00 app[web.1]: => Call with -d to detach 2011-04-26T01:24:29+00:00 app[web.1]: => Ctrl-C to shutdown server
Scaling a process type
Heroku runs one
web dyno for you automatically, but other process types don’t start by default. To launch a worker, you need to scale it up to one dyno:
$ heroku ps:scale worker=1 Scaling worker processes... done, now running 1
You can also scale the size of a dyno:
$ heroku ps:resize worker=standard-2x Resizing dynos and restarting specified processes... done worker dynos now standard-2x
ps to see the new process type running, for example:
$ heroku ps === web: `bundle exec rails server -p $PORT` web.1: up for 2m === worker: `env QUEUE=* bundle exec rake resque:work` worker.1: up for 5s
heroku logs --ps worker to view just the messages from the worker process type:
$ heroku logs --ps worker 2011-04-25T18:33:25-07:00 heroku[worker.1]: State changed from created to starting 2011-04-26T01:33:26+00:00 heroku[worker.1]: Running process with command: `env QUEUE=* bundle exec rake resque:work` 2011-04-25T18:33:29-07:00 heroku[worker.1]: State changed from starting to up 2011-04-26T01:33:29+00:00 app[worker.1]: (in /app)
The output we see here matches our local output, interleaved with system messages from Heroku’s system components such as the router and dyno manager.
You can scale up higher with the same command. For example, two web dynos and four worker dynos:
$ heroku ps:scale web=2 worker=4 Scaling web processes... done, now running 2 Scaling worker processes... done, now running 4 $ heroku ps === web: `bundle exec rails server -p $PORT` web.1: up for 7m web.2: up for 2s === worker: `env QUEUE=* bundle exec rake resque:work` worker.1: up for 7m worker.2: up for 3s worker.3: up for 2s worker.4: up for 3s
More process type examples
Procfile model of running processes types is extremely flexible. You can run any number of dynos with whatever arbitrary commands you want, and scale each independently.
For example, using Ruby you could run two types of queue workers, each consuming different queues:
worker: env QUEUE=* bundle exec rake resque:work urgentworker: env QUEUE=urgent bundle exec rake resque:work
These can then be scaled independently.
$ heroku ps:scale worker=1 urgentworker=5