Merge pull request #194 from opdemand/more-doc-updates

Gabriel Monroy · Gabriel Monroy · commit 8a46d2193c15 · 2013-09-24T14:17:27.000-07:00
More doc updates
diff --git a/README.md b/README.md
@@ -38,7 +38,7 @@ Before you get started, read about Deis core [concepts](http://docs.deis.io/en/l
  * What is a [Formation](http://docs.deis.io/en/latest/gettingstarted/concepts/#formations) and how does it relate to an application?
  * What are [Layers and Nodes](http://docs.deis.io/en/latest/gettingstarted/concepts/#layers), and how do they work with Chef?
  * How does the [Build, Release, Run](http://docs.deis.io/en/latest/gettingstarted/concepts/#build-release-run) process work?
- * How do I connect a Formation to [backing services](http://docs.deis.io/en/latest/gettingstarted/concepts/#backing-services)?
+ * How do I connect an application to [backing services](http://docs.deis.io/en/latest/gettingstarted/concepts/#backing-services)?
 
 Follow the steps below to install your own Deis platform on EC2. To complete the installation process, you will need [Git](http://git-scm.com), [RubyGems](http://rubygems.org/pages/download), [Pip](http://www.pip-installer.org/en/latest/installing.html), the [Amazon EC2 API Tools](http://aws.amazon.com/developertools/351), [EC2 Credentials](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/SettingUp_CommandLine.html#set_aws_credentials_linux) and a Chef Server with a working [Knife](http://docs.opscode.com/knife.html) client.
 
@@ -51,9 +51,7 @@ $ git clone https://github.com/opdemand/deis.git
 $ cd deis
 ```
 
-Cloning the default master branch will provide you with the latest development version
-of Deis.  If you want to deploy the latest stable release, make sure you checkout the
-most recent tag using ``git checkout vX.Y.Z``.
+Cloning the default master branch will provide you with the latest development version of Deis.  If you want to deploy the latest stable release, make sure you checkout the most recent tag using ``git checkout vX.Y.Z``.
 
 ### 2. Configure the Chef Server
 
@@ -82,6 +80,7 @@ $ sudo pip install deis
 $ deis register http://my-deis-controller.fqdn
 username: myuser
 password: 
+password (confirm): 
 email: myuser@example.com
 Registered myuser
 Logged in as myuser
@@ -101,17 +100,16 @@ Uploading EC2 credentials... done
 Use the Deis client to create a new formation named "dev" that
 has a default layer that serves as both runtime (hosts containers)
 and proxy (routes traffic to containers).  Scale the default layer
-up to two nodes.
+up to one node.
 
 ```bash
-$ deis formations:create dev --flavor=ec2-us-west-2
+$ deis formations:create dev --flavor=ec2-us-west-2 --domain=deisapp.com
 Creating formation... done, created dev
-
 Creating runtime layer... done in 1s
 
 Use `deis nodes:scale dev runtime=1` to scale a basic formation
 
-$ deis nodes:scale dev runtime=2
+$ deis nodes:scale dev runtime=1
 Scaling nodes... but first, coffee!
 ...done in 251s
 
@@ -123,18 +121,20 @@ Use `deis create --formation=dev` to create an application
 Change into your application directory and use  ``deis create --formation=dev`` 
 to create a new application attached to the dev formation.
 
-To deploy the application, use `git push deis master`.  
-Deis will automatically deploy Docker containers 
-and configure Nginx proxies to route requests to your application.
+To deploy the application, use `git push deis master`.  Deis will automatically deploy Docker containers and configure Nginx proxies to route requests to your application.
 
-Once your application is deployed, you use ``deis scale web=4`` to 
+Once your application is deployed, use ``deis scale web=4`` to 
 scale up web containers.  You can also use ``deis logs`` to view 
-aggregated application logs, or ``deis run`` to run one-off admin
+aggregated application logs, or ``deis run`` to run admin
 commands inside your application.
 
 To learn more, use `deis help` or browse [the documentation](http://docs.deis.io).
 
 ```bash
+$ deis create --formation=dev
+Creating application... done, created peachy-waxworks
+Git remote deis added
+    
 $ git push deis master
 Counting objects: 146, done.
 Delta compression using up to 8 threads.
@@ -154,9 +154,9 @@ Total 146 (delta 84), reused 47 (delta 22)
        Launching... done, v2
 
 -----> peachy-waxworks deployed to Deis
-       http://ec2-198.51.100.36.us-west-2.compute.amazonaws.com ...
+       http://peachy-waxworks.deisapp.com ...
 
-$ curl -s http://ec2-198.51.100.36.us-west-2.compute.amazonaws.com
+$ curl -s http://peachy-waxworks.deisapp.com
 Powered by Deis!
 
 $ deis scale web=4
@@ -166,10 +166,10 @@ done in 12s
 === peachy-waxworks Containers
  
 --- web: `node server.js`
-web.1 up 2013-09-23T19:02:30.745Z (dev-runtime-2)
+web.1 up 2013-09-23T19:02:30.745Z (dev-runtime-1)
 web.2 up 2013-09-23T19:36:48.741Z (dev-runtime-1)
 web.3 up 2013-09-23T19:36:48.758Z (dev-runtime-1)
-web.4 up 2013-09-23T19:36:48.771Z (dev-runtime-2)    
+web.4 up 2013-09-23T19:36:48.771Z (dev-runtime-1)
 ```
 
 ## Credits
diff --git a/docs/gettingstarted/concepts.rst b/docs/gettingstarted/concepts.rst
@@ -8,7 +8,7 @@ Concepts
 ========
 
 Deis is an application platform that deploys and scales `Twelve Factor`_ apps 
-using a formation of `Chef`_ nodes, `Docker`_ containers and `Nginx`_ proxies.
+using formations of `Chef`_ nodes, `Docker`_ containers and `Nginx`_ proxies.
 
 Formations
 ----------
@@ -25,31 +25,28 @@ easily.  Formations have two primary types of layers.
 
 Runtime Layers
 ^^^^^^^^^^^^^^
-Runtime layers service requests and run background tasks for the formation.
-Nodes in a runtime layer use a `Chef Databag`_  to deploy
-:ref:`Containers <container>` running a specific :ref:`Release`.  
+Runtime layers host :ref:`Containers <container>` for a formation.
+Nodes in a runtime layer use a `Chef Databag`_ to deploy containers for 
+each :ref:`application` in the formation.
 
 Proxy Layers
 ^^^^^^^^^^^^
-Proxy layers expose the formation to the outside world.
+Proxy layers expose :ref:`Applications <application>` to the outside world.
 Nodes in a proxy layer use a `Chef Databag`_ to configure routing of 
 inbound requests to :ref:`Containers <container>` hosted on runtime layers.
 
 Applications
 ------------
-
-An :ref:`application` lives on a :ref:`formation` where it services requests 
-and runs background jobs for a deployed git repository. Each application includes 
-:ref:`Containers <container>` used to run isolated processes, and a 
-:ref:`Release` that defines the current :ref:`Build` and :ref:`config` 
-deployed by containers. 
-
-Developers can use :ref:`Applications <application>` to push builds, change config
-and scale containers without worrying about the formation's underlying infrastructure. 
+An :ref:`application` lives on a :ref:`formation` where it uses 
+:ref:`Containers <container>` to process requests and run background jobs
+for a deployed git repository.
+Developers use :ref:`Applications <application>` to push code, change config,
+scale containers, view logs, or run admin commands --
+regardless of the formation's underlying infrastructure. 
 
 Build, Release, Run
 ------------------- 
-Deis enforces strict separation between Build, Release and Run stages
+Deis enforces strict separation between Build and Run stages
 following the `Twelve Factor model`_.
 
 Build Stage
@@ -72,19 +69,20 @@ config is changed, making it easy to rollback code and configuration.
 Run Stage
 ^^^^^^^^^
 The run stage updates Chef databags and `converges`_ all nodes in the formation.
-The databag specifies the current release, the placement of containers across 
-the runtime layer, and the configuration of the proxy layer.
-SSH is used to converge all of the nodes in the runtime layer followed 
-by all of the nodes in the proxy layer, making zero downtime deployment possible.
+The databag specifies the current application releases, 
+the placement of containers across the runtime layer, 
+and the configuration of the proxy layer.
+SSH is used to converge nodes in runtime layers followed 
+by nodes in proxy layers, making zero downtime deployment possible.
 
 Backing Services
 ----------------
 In keeping with `Twelve Factor`_ methodology, `backing services`_ like
 databases, queues and storage are decoupled and attached using `environment
-variables`_.  This allows formations to use backing services provided via
-different formations (through their proxy layer), or external/third-party 
-services accessible over the network.  The use of environment variables
-also allows formations to easily swap backing services when necessary.
+variables`_.  This allows applications to use backing services provided by
+other applications, or external/third-party services accessible over the network.  
+The use of environment variables makes it easy to swap backing services
+when necessary.
 
 See Also
 --------
diff --git a/docs/gettingstarted/installation.rst b/docs/gettingstarted/installation.rst
@@ -1,5 +1,5 @@
 ﻿:title: Installation
-:description:  Install your own Deis platform on EC2. Configure the Chef server, provision a Deis controller, install the Deis Client and create & scale a formation.
+:description:  Install your own Deis platform on EC2. Provision a Deis controller, Install the Deis Client, Create & Scale a Formation, Deploy & Scale an Application.
 
 .. _installation:
 
@@ -89,6 +89,7 @@ Registration will discover SSH keys automatically and use the
     $ deis register http://my-deis-controller.fqdn
     username: myuser
     password:
+    password (confirm):
     email: myuser@example.com
     Registered myuser
     Logged in as myuser
@@ -109,13 +110,12 @@ Registration will discover SSH keys automatically and use the
 Use the Deis client to create a new formation named "dev" that
 has a default layer that serves as both runtime (hosts containers)
 and proxy (routes traffic to containers).  Scale the default layer
-up to two nodes.
+up to one node.
 
 .. code-block:: console
 
     $ deis formations:create dev --flavor=ec2-us-west-2
     Creating formation... done, created dev
-    
     Creating runtime layer... done in 1s
     
     Use `deis nodes:scale dev runtime=1` to scale a basic formation
@@ -138,9 +138,9 @@ To deploy the application, use ``git push deis master``.
 Deis will automatically deploy Docker containers and configure Nginx proxies
 to route requests to your application.
 
-Once your application is deployed, you use ``deis scale web=4`` to 
+Once your application is deployed, use ``deis scale web=4`` to 
 scale up web containers.  You can also use ``deis logs`` to view 
-aggregated application logs, or ``deis run`` to run one-off admin
+aggregated application logs, or ``deis run`` to run admin
 commands inside your application.
 
 To learn more, use ``deis help`` or browse `the documentation`_.
@@ -150,6 +150,7 @@ To learn more, use ``deis help`` or browse `the documentation`_.
     $ deis create --formation=dev
     Creating application... done, created peachy-waxworks
     Git remote deis added
+    
     $ git push deis master
     Counting objects: 146, done.
     Delta compression using up to 8 threads.
@@ -169,9 +170,9 @@ To learn more, use ``deis help`` or browse `the documentation`_.
            Launching... done, v2
 
     -----> peachy-waxworks deployed to Deis
-           http://ec2-54-214-143-104.us-west-2.compute.amazonaws.com ...
+           http://peachy-waxworks.deisapp.com ...
 
-    $ curl -s http://ec2-54-214-143-104.us-west-2.compute.amazonaws.com
+    $ curl -s http://peachy-waxworks.deisapp.com
     Powered by Deis!
     
     $ deis scale web=4
@@ -181,10 +182,10 @@ To learn more, use ``deis help`` or browse `the documentation`_.
     === peachy-waxworks Containers
     
     --- web: `node server.js`
-    web.1 up 2013-09-23T19:02:30.745Z (dev-runtime-2)
+    web.1 up 2013-09-23T19:02:30.745Z (dev-runtime-1)
     web.2 up 2013-09-23T19:36:48.741Z (dev-runtime-1)
     web.3 up 2013-09-23T19:36:48.758Z (dev-runtime-1)
-    web.4 up 2013-09-23T19:36:48.771Z (dev-runtime-2)
+    web.4 up 2013-09-23T19:36:48.771Z (dev-runtime-1)
 
 
 .. _`Git`: http://git-scm.com
diff --git a/docs/terms/build.rst b/docs/terms/build.rst
@@ -1,12 +1,11 @@
 :title: Build
-:description: A Deis build refers to the output of a specific application build. Deis builds are created automatically using git push.
+:description: Deis builds are created automatically on the controller when a developer uses git push.
 :keywords: build, release, git, git push, deis
 
 .. _build:
 
 Build
 =====
-A Deis build refers to the output of a specific application build.
 Deis builds are created automatically on the controller when a 
 developer uses ``git push deis master``.
 
diff --git a/docs/terms/controller.rst b/docs/terms/controller.rst
@@ -13,8 +13,7 @@ the application platform.  A single controller manages multiple
 container formations.
 
 Controllers are tied to a configuration management backend (typically a 
-Chef Server) where data about users, applications and formations 
-is stored and updated.
+Chef Server) where data about users, applications and formations is stored.
 
 The controller is in charge of:
 
diff --git a/docs/terms/formation.rst b/docs/terms/formation.rst
@@ -1,11 +1,11 @@
 :title: Formation
-:description: A Deis formation is a set of infrastructure used to host applications and services
+:description: A Deis formation is a set of infrastructure used to host applications.
 :keywords: formation, deis
 
 .. _formation:
 
 Formation
 =========
-A :ref:`formation` is a set of infrastructure used to host :ref:`Applications <application>`
-and services. Each formation includes :ref:`Layers <layer>` of :ref:`Nodes <node>`,
-and is managed by a single :ref:`Controller`.
+A :ref:`formation` is a set of infrastructure used to host :ref:`Applications <application>`.
+Each formation includes :ref:`Layers <layer>` of :ref:`Nodes <node>` 
+that provide different services to the formation.
diff --git a/docs/terms/layer.rst b/docs/terms/layer.rst
@@ -13,14 +13,14 @@ easily.
 
 Runtime Layers
 ^^^^^^^^^^^^^^
-Runtime layers service requests and run background tasks for the formation.
-Nodes in a runtime layer use a configuration management system (e.g. Chef Server)
-to deploy :ref:`Containers <container>` running a specific :ref:`Release`.
+Runtime layers host :ref:`Containers <container>` for a formation.
+Nodes in a runtime layer use a `Chef Databag`_ to deploy containers for 
+each :ref:`application` in the formation.
 
 Proxy Layers
 ^^^^^^^^^^^^
-Proxy layers expose the formation to the outside world.
-Nodes in a proxy layer use configuration management to configure routing of 
+Proxy layers expose :ref:`Applications <application>` to the outside world.
+Nodes in a proxy layer use a `Chef Databag`_ to configure routing of 
 inbound requests to :ref:`Containers <container>` hosted on runtime layers.
 
 Dual Layers
@@ -34,3 +34,5 @@ Custom Layers
 It is also possible to create custom layers that don't provide runtime or proxy
 services to the formation.  This is useful for scaling and managing backing
 services built with Chef that need to be managed alongside a formation.
+
+.. _`Chef Databag`: http://docs.opscode.com/essentials_data_bags.html
