first pass at terms documentation

Gabriel Monroy · Gabriel Monroy · commit a39574f82a0c · 2013-08-05T17:04:06.000-06:00
diff --git a/docs/gettingstarted/concepts.rst b/docs/gettingstarted/concepts.rst
@@ -49,7 +49,7 @@ Build Stage
 The :ref:`Controller` includes a `Gitosis Server`_ that receives
 incoming git push requests over SSH and builds applications
 inside ephemeral Docker containers. 
-Tarballs of the /app directory are extracted into a :ref:`slug` and exposed 
+Tarballs of the /app directory are extracted into a slug and exposed 
 on the Controller using an Nginx static file server. 
 The slug is later downloaded by the runtime layer and bind-mounted
 into a Docker container for execution.
diff --git a/docs/terms/build.rst b/docs/terms/build.rst
@@ -6,3 +6,8 @@
 
 Build
 =====
+A Deis build refers to the output of a specific application build.
+Deis builds can be created automatically using git push, 
+or manually using the client.
+
+When a new build is created, a new :ref:`release` is created automatically.
diff --git a/docs/terms/config.rst b/docs/terms/config.rst
@@ -1,8 +1,13 @@
 :title: Config
-:description: What is Config?
-:keywords: config, release
+:description: What is Deis Config?
+:keywords: config, release, envvar, envvars, environment, variables
 
 .. _config:
 
 Config
 ======
+Config refers to a set of environment variables used by 
+:ref:`Containers <container>` in a :ref:`Formation's <formation>` 
+runtime :ref:`layer`.
+
+When Config is changed, a new :ref:`release` is created automatically.
diff --git a/docs/terms/container.rst b/docs/terms/container.rst
@@ -1,8 +1,14 @@
 :title: Container
-:description: What is a Container?
+:description: What is a Deis Container?
 :keywords: lxc container, lxc, container, docker
 
 .. _container:
 
 Container
 =========
+Deis containers are instances of `Docker`_ containers.
+Containers perform the actual work of a :ref:`Formation` by
+servicing requests or running background tasks as
+part of the runtime :ref:`Layer`.
+
+.. _`Docker`: http://docker.io/
diff --git a/docs/terms/controller.rst b/docs/terms/controller.rst
@@ -6,3 +6,22 @@
 
 Controller
 ==========
+The controller is the "brains" of the Deis platform.
+Each controller is tied to a single Chef organization.
+The controller is in charge of:
+
+* Processing Client API calls
+* Managing Chef Nodes
+* Managing Docker Containers
+* Configuring Nginx proxies
+
+The controller stack includes:
+
+* Django API Server for handling API calls
+* PostgreSQL database as a backing store for Django
+* Celery / RabbitMQ for dispatching tasks
+* Gitosis to handle access control for Git Push over SSH
+* Docker and Buildstep to process Heroku Buildpacks
+
+Follow the :ref:`Installation` process to setup your own private
+Deis controller.
diff --git a/docs/terms/flavor.rst b/docs/terms/flavor.rst
@@ -1,8 +1,19 @@
 :title: Flavor
-:description: What is a Flavor?
+:description: What is a Deis Flavor?
 :keywords: flavor
 
 .. _flavor:
 
 Flavor
 ======
+A flavor defines the configuration for :ref:`Nodes <node>` in a 
+:ref:`Layer`, including their:
+
+* Provider Type (e.g. EC2)
+* Launch Parameters (region, zone, etc)
+* Initial Configuration using `cloud-config`_
+
+The :ref:`Controller` comes pre-seeded with default flavors for EC2
+that use 64-bit Deis-optimized AMIs with an m1.medium instance size.
+
+.. _`cloud-config`: http://cloudinit.readthedocs.org/en/latest/topics/examples.html#install-and-run-chef-recipes
diff --git a/docs/terms/formation.rst b/docs/terms/formation.rst
@@ -1,8 +1,14 @@
 :title: Formation
-:description: What is a Formation?
+:description: What is a Deis Formation?
 :keywords: formation, deis
 
 .. _formation:
 
 Formation
 =========
+A :ref:`formation` is a set of infrastructure used to host a single application
+or service backed by a single git repository. Each formation includes
+:ref:`Layers <layer>` of :ref:`Nodes <node>` used to host services, a set of 
+:ref:`Containers <container>` used to run isolated processes, and a 
+:ref:`Release` that defines the current :ref:`Build` and :ref:`config` 
+deployed by containers.
diff --git a/docs/terms/index.rst b/docs/terms/index.rst
@@ -18,11 +18,11 @@ Terms
     node
     container
     
-    release
     build
     config
-    slug
+    release
     
-    provider
     flavor
+    provider
+    key
     
diff --git a/docs/terms/key.rst b/docs/terms/key.rst
@@ -0,0 +1,17 @@
+:title: Key
+:description: What is a Deis Key?
+:keywords: key, ssh
+
+.. _key:
+
+Key
+===
+Deis keys are SSH Keys used during the git push process.  Each user
+can use the client to manage a list of keys on the :ref:`Controller`.
+
+A user's keys are automatically added to every launched :ref:`Node`,
+allowing easy SSH access via:
+
+.. code-block:: console
+
+	$ ssh ubuntu@<node-fqdn>
diff --git a/docs/terms/layer.rst b/docs/terms/layer.rst
@@ -1,8 +1,28 @@
 :title: Layer
-:description: What is a Layer?
+:description: What is a Deis Layer?
 :keywords: layer
 
 .. _layer:
 
 Layer
 =====
+:ref:`Layers <layer>` are homogeneous groups of :ref:`Nodes <node>` that 
+perform work on behalf of a formation.  Each node in a layer has 
+the same :ref:`Flavor` and Chef configuration, allowing them to be scaled
+easily.
+
+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`.  
+
+Proxy Layers
+^^^^^^^^^^^^
+Proxy layers expose the formation 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.
+
+Custom Layers
+^^^^^^^^^^^^^
+It is also possible to create custom layers that contain custom run-lists.
diff --git a/docs/terms/node.rst b/docs/terms/node.rst
@@ -1,8 +1,10 @@
 :title: Node
-:description: What is a Node?
+:description: What is a Deis Node?
 :keywords: chef node, chef, node, deis
 
 .. _node:
 
 Node
 ====
+A node is a virtual machine instance that is part of a :ref:`Layer`.
+All Deis nodes are managed by a Chef Server. 
diff --git a/docs/terms/provider.rst b/docs/terms/provider.rst
@@ -1,8 +1,23 @@
 :title: Provider
-:description: What is a Provider?
+:description: What is a Deis Provider?
 :keywords: provider
 
 .. _provider:
 
 Provider
 ========
+A provider is a pluggable connector to a third-party cloud API, such as `Amazon EC2`_.
+Deis's supported providers come pre-installed on the :ref:`Controller`.
+
+Building a custom provider is simple.  It must publish 5 methods as Celery tasks:
+
+* build_layer - to create any shared infrastructure needed by the layer's nodes
+* destroy_layer - to destroy any shared infrastructure
+* launch_node - to provision a node and register it with the Chef Server
+* terminate_node - to destroy a node a remove its records from the Chef Server
+* converge_node - to force converge a node (using SSH or other means)
+
+Provider developers can review the `EC2 Reference Implementation`_.
+
+.. _`Amazon EC2`: http://aws.amazon.com/ec2/
+.. _`EC2 Reference Implementation`: https://github.com/opdemand/deis/blob/master/celerytasks/ec2.py
diff --git a/docs/terms/release.rst b/docs/terms/release.rst
@@ -1,8 +1,17 @@
 :title: Release
-:description: What is a Release?
-:keywords: release
+:description: What is a Deis Release?
+:keywords: release, deis
 
 .. _release:
 
 Release
 =======
+A Deis release is a combination of a :ref:`Build` with a :ref:`Config`.
+Each :ref:`Formation` is associated with one release at a time.
+Deis releases are numbered and increment by one (e.g. v1, v2, v3).
+
+:ref:`Containers <container>` in the runtime :ref:`Layer` of a :ref:`formation`
+use the release version to pull the correct code and configuration as
+part of their `Chef run`_.
+
+.. _`Chef run`: http://docs.opscode.com/essentials_nodes_chef_run.html
diff --git a/docs/terms/slug.rst b/docs/terms/slug.rst
