process-types-and-the-procfile.md

Process Types and the Procfile

Deis Workflow observes the process model. As part of this model, a Procfile may be used as a mechanism for declaring the commands that should be run by your application’s containers. You can use a Procfile to declare multiple processes for different types of application workers-- for example, an application server, a job execution timer, or a consumer of the Twitter streaming API.

Multiple process types can be scaled independently of one another.

Default Process Types

In the absence of a Procfile, a single, default process type is assumed for each application.

All applications built using Heroku's Buildpacks implicitly declare a web process type, which starts the application server. Rails 4, for example, has the following process type:

web: bundle exec rails server -p $PORT

All applications utilizing Dockerfile deployments have an implied cmd process type, which spawns the default process of a Docker image as specified by the Dockerfile's CMD directive:

$ cat Dockerfile
FROM centos:latest
COPY . /app
WORKDIR /app
CMD python -m SimpleHTTPServer 5000
EXPOSE 5000

For applications utilizing Docker image deployments, a cmd process type is also implied and spawns the default process of the image.

Declaring Process Types

Developers utilizing Heroku's Buildpacks or Dockerfile deployments and wishing to override the implied, default process types, or declare additional process types may do so by including a file named Procfile in the root of their application's source tree.

Developers utilizing Docker image deployments may accomplish this with a Procfile in their working directory or by referencing a Procfile using the --procfile option of the deis pull command. For example:

$ deis pull deis/example-go:latest --procfile="cmd: /app/bin/boot"

The format of a Procfile 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 web, worker, urgentworker, clock, etc.

<command> – a command line to launch the process, such as rake jobs:work.

!!! note The web and cmd process types are special as they’re the only process types that will receive HTTP traffic from Workflow’s routers. Other process types can be named arbitrarily.

Scaling Processes

Once an application has been deployed, its process types can be scaled independently of one another. For example, consider the following Procfile:

web: bundle exec rails server -p $PORT
worker: bundle exec rake resque:work

Given the Procfile above, the web process could be scaled out:

$ deis scale web=5

And the worker process could be left alone, or scaled out independently, to whatever extent is required:

$ deis scale worker=3

Scaling a process type directly changes the number of Containers running that process.

Web vs Cmd Process Types

When deploying to Deis Workflow using a Heroku Buildpack, Workflow boots the web process type to boot the application server. When you deploy an application that has a Dockerfile or uses Docker images, Workflow boots the cmd process type. Both act similarly in that they are exposed to the router as web applications. However, the cmd process type is special because, if left undefined, it is equivalent to running the container without any additional arguments. (i.e. The process specified by the Dockerfile or Docker image's CMD directive will be used.)

If migrating an application from Heroku Buildpacks to a Docker-based deployment, Workflow will not automatically convert the web process type to cmd. To do this, you'll have to manually scale down the old process type and scale the new process type up.