docs(using_deis): add Using Docker Images section

Author: Gabriel Monroy

docs/using_deis/deploy-application.rst

@@ -52,6 +52,8 @@ Deploying a Docker image onto Deis allows you to take a Docker image from either
 or a private registry and copy it over bit-for-bit, ensuring that you are running the same
 image in development or in your CI pipeline as you are in production.
 
+Learn how to use deploy applications on Deis :ref:`using-docker-images`.
+
 
 .. _`twelve-factor methodology`: http://12factor.net/
 .. _`Heroku Buildpacks`: https://devcenter.heroku.com/articles/buildpacks

docs/using_deis/index.rst

@@ -17,5 +17,6 @@ Using Deis
     deploy-application
     using-buildpacks
     using-dockerfiles
+    using-docker-images
     config-application
     manage-application

docs/using_deis/using-docker-images.rst

@@ -0,0 +1,90 @@
+:title: Deploying Docker Images on Deis
+:description: How to deploy applications on Deis using Docker Images
+
+.. _using-docker-images:
+
+Using Docker Images
+===================
+Deis supports deploying applications via an existing `Docker Image`_.
+This is useful for integrating Deis into Docker-based CI/CD pipelines.
+
+Prepare an Application
+----------------------
+Start by cloning an example application:
+
+.. code-block:: console
+
+    $ git clone https://github.com/deis/example-go.git
+    $ cd example-go
+    $ git checkout docker
+
+Next use your local ``docker`` client to build the image and push
+it to `DockerHub`_.
+
+.. code-block:: console
+
+    $ docker build -t <username>/example-go .
+    $ docker push <username>/example-go
+
+Docker Image Requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^
+In order to deploy Docker images, they must conform to the following requirements:
+
+ * The Docker image must EXPOSE only one port
+ * The exposed port must be an HTTP service that can be connected to an HTTP router
+ * A default CMD must be specified for running the container
+
+.. note::
+
+    Docker images which expose more than one port will hit `issue 1156`_.
+
+.. attention::
+
+    Support for non-HTTP services is coming soon
+
+Create an Application
+---------------------
+Use ``deis create`` to create an application on the :ref:`controller`.
+
+.. code-block:: console
+
+    $ mkdir -p /tmp/example-go && cd /tmp/example-go
+    $ deis create
+    Creating application... done, created example-go
+
+.. note::
+
+    The ``deis`` client uses the name of the current directory as the
+    default app name.
+
+Deploy the Application
+----------------------
+Use ``deis pull`` to deploy your application from `DockerHub`_ or
+a private registry.
+
+.. code-block:: console
+
+    $ deis pull gabrtv/example-go:latest
+    Creating build...  done, v2
+
+    $ curl -s http://example-go.local3.deisapp.com
+    Powered by Deis
+
+Because you are deploying a Docker image, the ``cmd`` process type is automatically scaled to 1 on first deploy.
+
+.. attention::
+
+    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`: http://docs.docker.io/introduction/understanding-docker/
+.. _`DockerHub`: https://registry.hub.docker.com/
+.. _`CMD instruction`: http://docs.docker.io/reference/builder/#cmd
+.. _`issue 1156`: https://github.com/deis/deis/issues/1156

docs/using_deis/using-dockerfiles.rst

@@ -19,10 +19,10 @@ If you do not have an existing application, you can clone an example application
 
 Dockerfile Requirements
 ^^^^^^^^^^^^^^^^^^^^^^^
-In order to deploy Dockerfile applications, they must conform to the following guidelines:
+In order to deploy Dockerfile applications, they must conform to the following requirements:
 
  * The Dockerfile must EXPOSE only one port
- * The first exposed port must be an HTTP service that can be connected to an HTTP router
+ * The exposed port must be an HTTP service that can be connected to an HTTP router
  * A default CMD must be specified for running the container
 
 .. note::
@@ -57,7 +57,7 @@ Use ``git push deis master`` to deploy your application.
     Total 13 (delta 2), reused 0 (delta 0)
     -----> Building Docker image
     Uploading context 4.096 kB
-    Uploading context 
+    Uploading context
     Step 0 : FROM deis/base:latest
      ---> 60024338bc63
     Step 1 : MAINTAINER OpDemand <info@opdemand.com>
@@ -100,17 +100,17 @@ Use ``git push deis master`` to deploy your application.
     Removing intermediate container 7eb8ec45dcb0
     Successfully built ea1a8cc93ca3
     -----> Pushing image to private registry
-    
+
            Launching... done, v2
-    
+
     -----> folksy-offshoot deployed to Deis
            http://folksy-offshoot.local.deisapp.com
 
            To learn more, use `deis help` or visit http://deis.io
 
     To ssh://git@local.deisapp.com:2222/folksy-offshoot.git
      * [new branch]      master -> master
-     
+
     $ curl -s http://folksy-offshoot.local.deisapp.com
     Welcome to Deis!
     See the documentation at http://docs.deis.io/ for more information.
@@ -132,4 +132,4 @@ Deis also supports scaling other process types as defined in a `Procfile`_.  To
 .. _`Docker Image`: http://docs.docker.io/introduction/understanding-docker/
 .. _`CMD instruction`: http://docs.docker.io/reference/builder/#cmd
 .. _`issue 1156`: https://github.com/deis/deis/issues/1156
-.. _`Procfile`: https://devcenter.heroku.com/articles/procfile
+.. _`Procfile`: https://devcenter.heroku.com/articles/procfile