docs(using_deis): Process Types and the Procfile

This document explains to users how they can use a Procfile to
specify process types for an application.

Author: Matthew Fisher

docs/using_deis/index.rst

@@ -15,6 +15,7 @@ Using Deis
     install-client
     register-user
     deploy-application
+    process-types
     using-buildpacks
     using-dockerfiles
     using-docker-images

docs/using_deis/process-types.rst

@@ -0,0 +1,91 @@
+:title: Process Types and the Procfile
+:description: First steps for using the 12 factor process model with Deis.
+
+.. _process-types:
+
+Process Types and the Procfile
+==============================
+
+A Procfile is a mechanism for declaring what commands are run by your application’s containers on
+the Deis 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.
+
+Process Types as Templates
+--------------------------
+
+A Procfile is a text file named ``Procfile`` placed in the root of your application that lists the
+process types in an application. Each process type is a declaration of a command that is executed
+when a container of that process type is started.
+
+All the language and frameworks using :ref:`Heroku's Buildpacks <using-buildpacks>` declare a
+``web`` process type, which starts the application server. Rails 3 has the following process type:
+
+.. code-block:: console
+
+    web: bundle exec rails server -p $PORT
+
+All applications using :ref:`Dockerfile deployments <using-dockerfiles>` have an implied ``cmd``
+process type, which spawns the default process of a Docker image:
+
+.. code-block:: console
+
+    $ cat Dockerfile
+    FROM centos:latest
+    COPY . /app
+    WORKDIR /app
+    CMD python -m SimpleHTTPServer 5000
+    EXPOSE 5000
+
+For applications using :ref:`Docker image deployments <using-docker-images>`, a ``cmd`` process
+type is also implied and spawns the default process of the image.
+
+Declaring Process Types
+-----------------------
+
+Process types are declared via a file named ``Procfile``, placed in the root of your app. Its
+format is one process type per line, with each line containing:
+
+.. code-block:: console
+
+    <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 Deis’s routers. Other process types can be named arbitrarily.
+
+Deploying to Deis
+-----------------
+
+A ``Procfile`` is not necessary to deploy most languages supported by Deis. The platform
+automatically detects the language and supplies a default ``web`` process type to boot the server.
+
+Creating an explicit Procfile is recommended for greater control and flexibility over your app.
+
+For Deis to use your Procfile, add the Procfile to the root of your application, then push to Deis:
+
+.. code-block:: console
+
+    $ git add .
+    $ git commit -m "Procfile"
+    $ git push deis master
+    ...
+    -----> Procfile declares process types: web, worker
+    Compiled slug size is 10.4MB
+
+           Launching... done, v2
+
+    -----> unisex-huntress deployed to Deis
+           http://unisex-huntress.example.com
+
+For docker image deployments, a Procfile in the current directory or via the ``--procfile`` option
+flag will be used as the default process types for the application.
+
+.. _`process model`: https://devcenter.heroku.com/articles/process-model

docs/using_deis/using-docker-images.rst

@@ -72,13 +72,6 @@ Because you are deploying a Docker image, the ``cmd`` process type is automatica
 
     Support for Docker registry authentication is coming soon
 
-Define Process Types
---------------------
-Docker containers have a default command usually specified by a `CMD instruction`_.
-Deis uses the ``cmd`` process type to refer to this default command.
-
-Process types other than ``cmd`` are not supported when using Docker images.
-
 
 .. _`Docker Image`: https://docs.docker.com/introduction/understanding-docker/
 .. _`DockerHub`: https://registry.hub.docker.com/

docs/using_deis/using-dockerfiles.rst

@@ -113,16 +113,6 @@ Use ``git push deis master`` to deploy your application.
 
 Because a Dockerfile application is detected, the ``cmd`` process type is automatically scaled to 1 on first deploy.
 
-Define Process Types
---------------------
-Docker containers have a default command usually specified by a `CMD instruction`_.
-Deis uses the ``cmd`` process type to refer to this default command.
-
-Deis also supports scaling other process types as defined in a `Procfile`_.  To use this functionality, you must:
-
-1. Define process types with a `Procfile`_ in the root of your repository
-2. Include a ``start`` executable that can be called with: ``start <process-type>``
-
 
 .. _`Dockerfile`: https://docs.docker.com/reference/builder/
 .. _`Docker Image`: https://docs.docker.com/introduction/understanding-docker/