Merge pull request #2456 from gabrtv/doc-review

Gabriel Monroy · Gabriel Monroy · commit 960b41d4a87d · 2014-11-10T18:31:48.000-07:00
Update documentation in preparation for stable release
diff --git a/controller/web/static/js/checkURL.js b/controller/web/static/js/checkURL.js
@@ -6,7 +6,14 @@ var path = window.location.pathname.split('/');
 var cleanedPath = $.grep(path,function(n){ return(n) });
 
 // the second to last path segment is the section
-switch(cleanedPath[cleanedPath.length-2]) {
+// unless there's only 1 segment
+if (cleanedPath.length == 1) {
+    path = cleanedPath[0];
+} else {
+    path = cleanedPath[cleanedPath.length-2];
+}
+
+switch(path) {
   case 'understanding_deis':
     $('.toctree-l1 > a:contains("Understanding Deis")').attr('state', 'open');
     break;
@@ -19,6 +26,9 @@ switch(cleanedPath[cleanedPath.length-2]) {
   case 'managing_deis':
     $('.toctree-l1 > a:contains("Managing Deis")').attr('state', 'open');
     break;
+  case 'troubleshooting_deis':
+    $('.toctree-l1 > a:contains("Troubleshooting Deis")').attr('state', 'open');
+    break;
   case 'customizing_deis':
     $('.toctree-l1 > a:contains("Customizing Deis")').attr('state', 'open');
     break;
diff --git a/docs/contributing/overview.rst b/docs/contributing/overview.rst
@@ -10,23 +10,26 @@ Interested in contributing to the Deis project?  There are lots of ways to help.
 
 File Bugs & Enhancements
 ------------------------
-Find a bug? Want to see a new feature? Have a request
-for the maintainers? Open a `GitHub issue`_ and we’ll get the conversation
-started.
+Find a bug? Want to see a new feature? Have a request for the maintainers?
+Open a `GitHub issue`_ and we’ll get the conversation started.
 
 Write Documentation
 -------------------
-We are always looking to improve and expand our
-documentation. Most docs reside in the main repository under the `docs/`_
-directory. Simply fork the project, update docs and send us a pull request.
+We are always looking to improve and expand our documentation.
+Most docs reside in the main repository under the `docs/`_ directory.
+Simply fork the project, update docs and send us a pull request.
+
+Contribute Code
+---------------
+We are always looking for help improving the core framework, modules, tooling and test coverage.
+Interested in contributing code? Let’s chat in IRC. Make sure to check out issues tagged `easy-fix`_.
+
+Share your Experience
+---------------------
+Interact with the community on our user mailing list or live in our IRC channel,
+#deis on Freenode, where you can chat with other Deis users any time of day.
 
-Improve Deis Core
------------------
-Deis core is a Django/Celery application with a Python CLI.
-We are always looking for help improving the core framework, tooling and test
-coverage. Interested in contributing to Deis core? Let’s chat in IRC.
 
 .. _`Github issue`: https://github.com/deis/deis/issues/new
 .. _`docs/`: https://github.com/deis/deis/tree/master/docs
-.. _`deis-cookbook`: https://github.com/deis/deis-cookbook
-.. _`EC2 Example`: https://github.com/deis/deis/blob/master/celerytasks/ec2.py
+.. _`easy-fix`: https://github.com/deis/deis/labels/easy-fix
diff --git a/docs/installing_deis/digitalocean.rst b/docs/installing_deis/digitalocean.rst
@@ -6,8 +6,7 @@
 DigitalOcean
 ============
 
-In this tutorial, we will show you how to set up your own 3-node cluster on DigitalOcean. This
-guide is also available in DigitalOcean's `Community site`_, so check out their guide as well!
+In this tutorial, we will show you how to set up your own 3-node cluster on DigitalOcean.
 
 Prerequisites
 -------------
@@ -49,7 +48,7 @@ that, create at least three Droplets with the following specifications:
  - Select your SSH key from the list
 
 If private networking is not available in your region, swap out ``$private_ipv4`` with
-``$public_ipv4`` in the user-data file. 
+``$public_ipv4`` in the user-data file.
 
 If you want to use the script:
 
@@ -124,7 +123,6 @@ Now that you've finished provisioning a cluster, please refer to :ref:`install_d
 start installing the platform.
 
 
-.. _`Community site`: https://www.digitalocean.com/community/tutorials/how-to-set-up-a-deis-cluster-on-digitalocean
 .. _`docl`: https://github.com/nathansamson/docl#readme
 .. _`Deis Control Utility`: https://github.com/deis/deis/tree/master/deisctl#readme
 .. _`DNS control panel`: https://cloud.digitalocean.com/domains
diff --git a/docs/installing_deis/index.rst b/docs/installing_deis/index.rst
@@ -5,7 +5,7 @@
 .. _provision-controller:
 
 Installing Deis
-================
+===============
 
 Provisioning Deis is a matter of creating one or more :ref:`concepts_coreos`
 machines and using :ref:`install_deisctl` to install and start Deis.
@@ -21,14 +21,14 @@ with CoreOS.
 .. toctree::
 
     quick-start
-    install-deisctl
-    install-platform
-    digitalocean
+
     aws
-    vagrant
+    digitalocean
     gce
     rackspace
+    vagrant
     baremetal
-
+    install-deisctl
+    install-platform
 
 .. _`CoreOS Documentation`: https://coreos.com/docs/
diff --git a/docs/installing_deis/install-deisctl.rst b/docs/installing_deis/install-deisctl.rst
@@ -3,8 +3,8 @@
 
 .. _install_deisctl:
 
-Installing the Deis Control Utility
-===================================
+Install deisctl
+===============
 
 The Deis Control Utility, or ``deisctl`` for short, is a command-line client used to configure and
 manage the Deis Platform.
diff --git a/docs/installing_deis/install-platform.rst b/docs/installing_deis/install-platform.rst
@@ -3,12 +3,12 @@
 
 .. _install_deis_platform:
 
-Installing the Deis Platform
-============================
+Install the Deis Platform
+=========================
 
 .. important::
 
-    Before installing the platform, please see :ref:`install_deisctl` first.
+    Before installing the platform, please see :ref:`install_deisctl`.
 
 From the computer you installed the Deis Control Utility, we will provision the Deis platform.
 Ensure your SSH agent is running and select the private key that corresponds to the SSH key added
diff --git a/docs/installing_deis/quick-start.rst b/docs/installing_deis/quick-start.rst
@@ -4,17 +4,17 @@
 Quick Start
 ===========
 
-These steps will help you get started with deploying a multi-node Deis cluster.
+These steps will help you provision a Deis cluster.
 
 
 .. _generate_ssh_key:
 
 Generate an SSH key
 -------------------
 
-To avoid problems deploying/launching apps later on, it is necessary to install `CoreOS`_ to disk
-with an SSH key without a passphrase. The following command will generate a new keypair named
-"deis":
+The ``deisctl`` utility communicates with remote machines over an SSH tunnel.
+If you don't already have an SSH key, the following command will generate
+a new keypair named "deis":
 
 .. code-block:: console
 
@@ -26,8 +26,7 @@ with an SSH key without a passphrase. The following command will generate a new
 Generate a New Discovery URL
 ----------------------------
 
-To get started with provisioning Deis, we will need to generate a new Discovery URL. Discovery URLs
-help connect `etcd`_ instances together by storing a list of peer addresses and metadata under a
+Discovery URLs help connect `etcd`_ instances together by storing a list of peer addresses and metadata under a
 unique address. You can generate a new discovery URL for use in your platform by
 running the following from the root of the repository:
 
@@ -44,11 +43,11 @@ Choose a Provider
 
 Choose one of the following providers and deploy a new cluster:
 
-- :ref:`deis_on_digitalocean`
 - :ref:`deis_on_aws`
-- :ref:`deis_on_vagrant`
+- :ref:`deis_on_digitalocean`
 - :ref:`deis_on_gce`
 - :ref:`deis_on_rackspace`
+- :ref:`deis_on_vagrant`
 - :ref:`deis_on_bare_metal`
 
 
@@ -61,9 +60,9 @@ See :ref:`configure-dns` for more information on properly setting up your DNS re
 Install Deis Platform
 ---------------------
 
-Now that you've finished provisioning a cluster, please refer to :ref:`install_deisctl` and :ref:`install_deis_platform` to
-start the platform.
+Now that you've finished provisioning a CoreOS cluster,
+please refer to :ref:`install_deisctl` and :ref:`install_deis_platform`.
 
 
 .. _`CoreOS`: https://coreos.com/
-.. _`etcd`: https://github.com/coreos/etcd
+.. _`etcd`: https://github.com/coreos/etcd
diff --git a/docs/managing_deis/configure-load-balancers.rst b/docs/managing_deis/configure-load-balancers.rst
@@ -1,19 +1,17 @@
-:title: Configure load balancers
+:title: Configure Load Balancers
 :description: Configure load balancers for your Deis Cluster
 
 .. _configure-load-balancers:
 
-Configure load balancers
+Configure Load Balancers
 ------------------------
 
 .. image:: DeisLoadBalancerDiagram.png
     :alt: Deis Load Balancer Diagram
 
-For a one-node Deis cluster, there is one router and one controller, so load balancing is unnecessary.
-You can proceed with the next section: :ref:`configure-dns`.
-
-On a multi-node cluster, however, there are probably multiple routers scheduled to the cluster, and
-these can potentially move hosts. Therefore, it is recommended that you configure a load balancer
+Deis includes multiple routers scheduled to the cluster as part of the router mesh.
+In the event of a host failure, these routers can move hosts.
+Therefore, it is recommended that you configure a load balancer
 to operate in front of the Deis cluster to serve application traffic.
 
 These ports need to be open on the load balancers:
diff --git a/docs/managing_deis/operational_tasks.rst b/docs/managing_deis/operational_tasks.rst
@@ -15,7 +15,7 @@ Managing users
 There are two classes of Deis users: normal users and administrators.
 
 * Users can use most of the features of Deis - creating and deploying applications, adding/removing domains, etc.
-* Administrators can perform all the actions that users can, but they can also create, edit, and destroy clusters.
+* Administrators can perform all the actions that users can, but they also have owner access to all applications.
 
 The first user created on a Deis installation is automatically an administrator.
 
diff --git a/docs/managing_deis/platform_logging.rst b/docs/managing_deis/platform_logging.rst
@@ -9,9 +9,8 @@ Platform logging
 Logging for Deis components and deployed applications is handled by two components:
 :ref:`logger` and :ref:`logspout`.
 
-``deis-logspout`` is based on progrium's `logspout`_ project and runs on all CoreOS hosts. It
-collects logs from running containers and sends their logs to ``/deis/logs/host`` and
-``/deis/logs/port``.
+``deis-logspout`` runs on all CoreOS hosts, collects logs from running containers
+and sends their logs to ``/deis/logs/host`` and ``/deis/logs/port``.
 
 ``deis-logger`` collects the logs sent by logspout and archives them for use by :ref:`Controller`
 when a client runs ``deis logs``. This component publishes its host and port to ``/deis/logs/host``
diff --git a/docs/managing_deis/platform_monitoring.rst b/docs/managing_deis/platform_monitoring.rst
@@ -6,7 +6,7 @@
 Platform monitoring
 ===================
 
-While Deis itself doesn't have a built-in monitoring platform, Deis components and deployed
+While Deis itself doesn't have a built-in monitoring system, Deis components and deployed
 applications alike run entirely within Docker containers. This means that monitoring tools and
 services which support Docker containers should work with Deis. A few tools and monitoring services
 which support Docker integrations are detailed below.
diff --git a/docs/managing_deis/security_considerations.rst b/docs/managing_deis/security_considerations.rst
@@ -6,10 +6,16 @@
 Security considerations
 ========================
 
+.. important::
+
+    Deis is not suitable for multi-tenant environments
+    or hosting untrusted code.
+
 A major goal of Deis is to be operationally secure and trusted by operations engineers in every deployed
 environment. There are, however, two notable security-related considerations to be aware of
 when deploying Deis.
 
+
 Access to etcd
 --------------
 Since all Deis configuration settings are stored in etcd (including passwords, keys, etc.), any access
diff --git a/docs/managing_deis/ssl-endpoints.rst b/docs/managing_deis/ssl-endpoints.rst
@@ -4,10 +4,10 @@
 
 .. _ssl-endpoints:
 
-SSL Endpoints
-=============
+SSL/TLS Endpoints
+=================
 
-SSL (Secure Sockets Layer) is the standard security technology for establishing an encrypted link
+SSL/TLS is the standard security technology for establishing an encrypted link
 between a web server and a browser. This link ensures that all data passed between the web server
 and browsers remain private and integral.
 
diff --git a/docs/managing_deis/upgrading-deis.rst b/docs/managing_deis/upgrading-deis.rst
@@ -27,16 +27,6 @@ and then reinstall platform components.
     Always use a version of ``deisctl`` that matches the Deis release.
     Verify this with ``deisctl --version``.
 
-.. note::
-
-    In-place upgrades are supported starting from Deis version 0.14.0
-
-.. note::
-
-    Occasionally, when upgrading Deis, we have seen deisctl stuck in a restart loop on ``deis-store`` components.
-    The workaround for this is to restart the store-daemons with ``deisctl restart store-daemon``. If run while
-    the original ``deisctl start platform`` command is still running, it should resume almost immediately.
-
 Use the following steps to perform an in-place upgrade of your Deis cluster.
 
 .. code-block:: console
diff --git a/docs/understanding_deis/architecture.rst b/docs/understanding_deis/architecture.rst
@@ -17,9 +17,8 @@ System Diagram
 .. image:: DeisSystemDiagram.png
     :alt: Deis System Diagram
 
+Operators use the ``Deisctl API`` to stand up the cluster's Control Plane, Data Plane and Router Mesh.
 End-users of the platform interact with the Control Plane using the ``Deis API``.
-Operators use the ``Deisctl API`` to stand up the cluster's Control Plane, Data Plane
-and Router Mesh.
 
 The Control Plane dispatches work to the Data Plane via a scheduler.
 The Router Mesh is used to route traffic to both the Control Plane and Data Plane.
@@ -39,7 +38,7 @@ Control plane components (in blue) are all implemented as Docker containers.
 
 The :ref:`store` component consists of a number of smaller components that represent a
 containerized Ceph cluster which provides a blob storage API and POSIX filesystem API
-for control plane's stateful components:
+for the control plane's stateful components:
 
  * :ref:`registry` - a Docker registry used to hold images and configuration data
  * :ref:`database` - a Postgres database used to store platform state
@@ -58,7 +57,7 @@ Data Plane
 
 The Data Plane is where :ref:`Containers <container>` (in blue) are run on behalf of end-users.
 
-The platform scheduler is charge of placing containers on hosts in the data plane.
+The platform scheduler is in charge of placing containers on hosts in the data plane.
 Deis also requires a few lightweight components on these hosts:
 
  * :ref:`publisher` - publishes end-user containers to the :ref:`router`
diff --git a/docs/understanding_deis/concepts.rst b/docs/understanding_deis/concepts.rst
@@ -69,8 +69,8 @@ Build, Release, Run
 
 Build Stage
 ^^^^^^^^^^^
-The :ref:`builder` processes incoming ``git push`` requests builds applications
-inside ephemeral Docker containers, creating a new Docker image.
+The :ref:`builder` processes incoming ``git push`` requests and builds applications
+inside ephemeral Docker containers, resulting in a new Docker image.
 
 Release Stage
 ^^^^^^^^^^^^^
diff --git a/docs/using_deis/config-application.rst b/docs/using_deis/config-application.rst
@@ -41,8 +41,8 @@ the application to an external PostgreSQL database.
 
 Detachments can be performed with ``deis config:unset``.
 
-Add Custom Domains to the Application
--------------------------------------
+Custom Domains
+--------------
 
 You can use ``deis domains`` to add or remove custom domains to your application:
 
diff --git a/docs/using_deis/install-client.rst b/docs/using_deis/install-client.rst
@@ -10,31 +10,19 @@ with a Deis :ref:`Controller`. You must install the client to use Deis.
 
 Install the Deis Client
 -----------------------
-Your Deis client should match your server's version. For development, an
-easy way to ensure this is to run `client/deis.py` in the code repository
-you used to provision the server. You can make a symlink or shell alias for
-`deis` to that file:
 
-.. code-block:: console
-
-    $ pip install docopt==0.6.2 python-dateutil==2.2 requests==2.4.3 termcolor==1.1.0
-    $ sudo ln -fs $(pwd)/client/deis.py /usr/local/bin/deis
-    $ deis
-    Usage: deis <command> [<args>...]
-
-If you don't have Python_, install the latest `deis` binary executable for
-Linux or Mac OS X with this command:
+Install the latest ``deis`` client for Linux or Mac OS X with:
 
 .. code-block:: console
 
     $ curl -sSL http://deis.io/deis-cli/install.sh | sh
 
-The installer puts `deis` in your current directory, but you should move it
+The installer puts ``deis`` in your current directory, but you should move it
 somewhere in your $PATH.
 
 Proxy Support
 -------------
-Set the ```http_proxy``` or ```https_proxy``` environment variable to enable proxy support:
+Set the ``http_proxy`` or ``https_proxy`` environment variable to enable proxy support:
 
 .. code-block:: console
 
diff --git a/docs/using_deis/register-user.rst b/docs/using_deis/register-user.rst
diff --git a/docs/using_deis/using-buildpacks.rst b/docs/using_deis/using-buildpacks.rst
diff --git a/docs/using_deis/using-docker-images.rst b/docs/using_deis/using-docker-images.rst
diff --git a/docs/using_deis/using-dockerfiles.rst b/docs/using_deis/using-dockerfiles.rst
