Merge pull request #2447 from bacongobbler/2446-ssh-key-docs

docs(installing_deis): add quick start guide

Author: Matthew Fisher

docs/installing_deis/baremetal.rst

@@ -15,16 +15,10 @@ machine running entirely from RAM. Then, you can `install CoreOS to disk`_.
     Deis requires CoreOS version 472.0.0 or more recent.
 
 
-Generate SSH key
+Generate SSH Key
 ----------------
 
-To avoid problems deploying/launching apps later on it is necessary to install `CoreOS`_ to disk
-with a SSH key without a passphrase. The following command will generate a new keypair named
-"deis":
-
-.. code-block:: console
-
-    $ ssh-keygen -q -t rsa -f ~/.ssh/deis -N '' -C deis
+Please refer to :ref:`generate_ssh_key` for generating a new SSH key.
 
 
 Customize user-data
@@ -34,17 +28,7 @@ Customize user-data
 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
-unique address. You can generate a new discovery URL for use in your platform by
-running the following from the root of the repository:
-
-.. code-block:: console
-
-    $ make discovery-url
-
-This will write a new discovery URL to the user-data file. Some convenience scripts are supplied in
-this user-data file, so it is mandatory for provisioning Deis.
+Please refer to :ref:`generate_discovery_url` for generating a new Discovery URL.
 
 
 SSH Key
@@ -166,7 +150,6 @@ disk. Add the following block to the ``write_files`` section:
 
 .. _`cluster size`: https://github.com/coreos/etcd/blob/master/Documentation/optimal-cluster-size.md
 .. _`CoreOS`: https://coreos.com/
-.. _`etcd`: https://github.com/coreos/etcd
 .. _`install CoreOS to disk`: https://coreos.com/docs/running-coreos/bare-metal/installing-to-disk/
 .. _`iPXE`: https://coreos.com/docs/running-coreos/bare-metal/booting-with-ipxe/
 .. _`PXE`: https://coreos.com/docs/running-coreos/bare-metal/booting-with-pxe/

docs/installing_deis/digitalocean.rst

@@ -14,8 +14,6 @@ Prerequisites
 
 To complete this guide, you must have the following:
 
- - An SSH key for running operator's commands against the cluster using ``deisctl``
- - An SSH key for authorizing yourself against Deis' builder
  - A domain to point to the cluster
  - The ability to provision at least 3 DigitalOcean Droplets that are 2GB or greater
 
@@ -24,21 +22,16 @@ In order to provision the cluster, we will need to install a couple of administr
 `Deis Control Utility`_, which will assist us with installing, configuring and managing the Deis
 platform.
 
-Generate a New Discovery URL
-----------------------------
+Generate SSH Key
+----------------
 
-To get started with provisioning the Droplets, 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 unique address. You can generate a new discovery URL for use in your platform by
-running the following from the root of the repository:
+Please refer to :ref:`generate_ssh_key` for generating a new SSH key.
 
-.. code-block:: console
+Generate a New Discovery URL
+----------------------------
 
-    $ make discovery-url
+Please refer to :ref:`generate_discovery_url` for generating a new Discovery URL.
 
-This will write a new discovery URL to the user-data file. This file is used by DigitalOcean's v2
-metadata API to create and customize each machine in our cluster to our liking. Some convenience
-scripts are supplied in this user-data file, so it is mandatory for provisioning Deis.
 
 Create CoreOS Droplets
 ----------------------
@@ -135,5 +128,4 @@ start installing the platform.
 .. _`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
-.. _`etcd`: https://github.com/coreos/etcd
 .. _`this tutorial`: https://www.digitalocean.com/community/tutorials/how-to-set-up-a-host-name-with-digitalocean

docs/installing_deis/index.rst

@@ -20,6 +20,7 @@ with CoreOS.
 
 .. toctree::
 
+    quick-start
     install-deisctl
     install-platform
     digitalocean

docs/installing_deis/quick-start.rst

@@ -0,0 +1,69 @@
+:title: Quick Start
+:description: How to start provisioning a multi-node Deis cluster
+
+Quick Start
+===========
+
+These steps will help you get started with deploying a multi-node 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":
+
+.. code-block:: console
+
+    $ ssh-keygen -q -t rsa -f ~/.ssh/deis -N '' -C deis
+
+
+.. _generate_discovery_url:
+
+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
+unique address. You can generate a new discovery URL for use in your platform by
+running the following from the root of the repository:
+
+.. code-block:: console
+
+    $ make discovery-url
+
+This will write a new discovery URL to the user-data file. Some essential scripts are supplied in
+this user-data file, so it is mandatory for provisioning Deis.
+
+
+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_gce`
+- :ref:`deis_on_rackspace`
+- :ref:`deis_on_bare_metal`
+
+
+Configure DNS
+-------------
+
+See :ref:`configure-dns` for more information on properly setting up your DNS records with Deis.
+
+
+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.
+
+
+.. _`CoreOS`: https://coreos.com/
+.. _`etcd`: https://github.com/coreos/etcd

docs/installing_deis/rackspace.rst

@@ -40,11 +40,16 @@ Your account ID is displayed in the upper right-hand corner of the cloud control
 API key can be found on the Account Settings page.
 
 
+Generate SSH Key
+----------------
+
+Please refer to :ref:`generate_ssh_key` for generating a new SSH key.
+
+
 Set up your keys
 ----------------
 
-Choose an existing keypair or generate a new one, if desired. Tell supernova about the key pair and
-give it an identifiable name:
+Tell supernova about the key pair and give it an identifiable name:
 
 .. code-block:: console
 
@@ -54,14 +59,7 @@ give it an identifiable name:
 Generate a New Discovery URL
 ----------------------------
 
-To get started with provisioning the nodes, 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 unique address. You can generate a new discovery URL for use in your platform by
-running the following from the root of the repository:
-
-.. code-block:: console
-
-    $ make discovery-url
+Please refer to :ref:`generate_discovery_url` for generating a new Discovery URL.
 
 
 Choose number of instances
@@ -74,7 +72,7 @@ By default, the provision script will provision 3 servers. You can override this
     $ DEIS_NUM_INSTANCES=5 ./provision-rackspace-cluster.sh deis-key
 
 Note that for scheduling to work properly, clusters must consist of at least 3 nodes and always have an odd number of members.
-For more information, see [optimal etcd cluster size](https://github.com/coreos/etcd/blob/master/Documentation/optimal-cluster-size.md).
+For more information, see `optimal etcd cluster size`_.
 
 Deis clusters of less than 3 nodes are unsupported.
 
@@ -127,6 +125,6 @@ start installing the platform.
 
 .. _`contrib/rackspace`: https://github.com/deis/deis/tree/master/contrib/rackspace
 .. _`CoreOS on Rackspace`: https://coreos.com/docs/running-coreos/cloud-providers/rackspace/
-.. _etcd: https://github.com/coreos/etcd
+.. _`optimal etcd cluster size`: https://github.com/coreos/etcd/blob/master/Documentation/optimal-cluster-size.md
 .. _Rackspace: https://github.com/deis/deis/tree/master/contrib/rackspace#readme
 .. _`contrib/rackspace`: https://github.com/deis/deis/tree/master/contrib/rackspace

docs/installing_deis/vagrant.rst

@@ -22,20 +22,16 @@ Please install `Vagrant`_ v1.6.5+ and `VirtualBox`_.
     website.
 
 
-Generate a New Discovery URL
-----------------------------
+Generate SSH Key
+----------------
 
-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
-unique address. You can generate a new discovery URL for use in your platform by
-running the following from the root of the repository:
+Please refer to :ref:`generate_ssh_key` for generating a new SSH key.
 
-.. code-block:: console
 
-    $ make discovery-url
+Generate a New Discovery URL
+----------------------------
 
-This will write a new discovery URL to the user-data file. Some convenience scripts are supplied in
-this user-data file, so it is mandatory for provisioning Deis.
+Please refer to :ref:`generate_discovery_url` for generating a new Discovery URL.
 
 
 Boot CoreOS
@@ -74,4 +70,3 @@ start installing the platform.
 
 .. _Vagrant: http://www.vagrantup.com/
 .. _VirtualBox: https://www.virtualbox.org/wiki/Downloads
-.. _etcd: https://github.com/coreos/etcd