docs(*): clarify local cluster settings

Author: carmstrong

docs/installing_deis/install-platform.rst

@@ -26,6 +26,10 @@ to your CoreOS nodes:
     $ eval `ssh-agent -s`
     $ ssh-add ~/.ssh/deis
 
+.. note::
+
+    For Vagrant clusters: ``ssh-add ~/.vagrant.d/insecure_private_key``
+
 Find the public IP address of one of your nodes, and export it to the DEISCTL_TUNNEL environment
 variable (substituting your own IP address):
 
@@ -39,6 +43,10 @@ If you set up the "convenience" DNS records, you can just refer to them via
 
     $ export DEISCTL_TUNNEL="deis-1.example.com"
 
+.. note::
+
+    For Vagrant clusters: ``export DEISCTL_TUNNEL=172.17.8.100``
+
 This is the IP address where deisctl will attempt to communicate with the cluster. You can test
 that it is working properly by running ``deisctl list``. If you see a single line of output, the
 control utility is communicating with the nodes.
@@ -56,6 +64,10 @@ We'll also need to tell the controller which domain name we are deploying applic
 
     $ deisctl config platform set domain=example.com
 
+.. note::
+
+    For Vagrant clusters: ``deisctl config platform set domain=local3.deisapp.com``
+
 Once finished, run this command to provision the Deis platform:
 
 .. code-block:: console

docs/installing_deis/vagrant.rst

@@ -60,8 +60,13 @@ Configure DNS
 
 For convenience, we have set up a few DNS records for users running on Vagrant.
 ``local3.deisapp.com`` is set up for 3-node clusters and ``local5.deisapp.com`` is set up for
-5-node clusters. If you want to set up your own DNS records, see :ref:`configure-dns` for more
-information.
+5-node clusters.
+
+Since ``local3.deisapp.com`` is your cluster domain, use ``local3.deisapp.com`` anywhere you see
+``example.com`` in the documentation.
+
+It is not necessary to configure DNS for Vagrant clusters, but it is possible - if you want to set up
+your own DNS records, see :ref:`configure-dns` for more information.
 
 
 Install Deis Platform

docs/managing_deis/configure-dns.rst

@@ -6,8 +6,8 @@
 Configure DNS
 =============
 
-For local clusters, we've created the DNS record ``local.deisapp.com`` which resolves to the IP of the first VM, 172.17.8.100.
-You can use ``local.deisapp.com`` to both log into the controller and to access applications that you've deployed (they will be subdomains of ``local.deisapp.com``, like ``happy-unicorn.local.deisapp.com``). Similarly, you can use ``local3.deisapp.com`` or ``local5.deisapp.com`` for 3- and 5-node clusters, respectively. No DNS configuration is necessary for local clusters.
+For Vagrant clusters, we've created the DNS record ``local.deisapp.com`` which resolves to the IP of the first VM, 172.17.8.100.
+You can use ``local.deisapp.com`` to both log into the controller and to access applications that you've deployed (they will be subdomains of ``local.deisapp.com``, like ``happy-unicorn.local.deisapp.com``). Similarly, you can use ``local3.deisapp.com`` or ``local5.deisapp.com`` for 3- and 5-node clusters, respectively. No DNS configuration is necessary for Vagrant clusters.
 
 For Deis clusters hosted elsewhere (EC2, Rackspace, DigitalOcean, Google Compute Engine, bare metal, etc.), DNS records will need to be created to point to the cluster. For a one-node cluster, we schedule and launch one router, and deis-router and deis-controller will run on the same host. So, the DNS record specified below can be configured to point to this one machine.
 
@@ -26,7 +26,7 @@ Deis requires one wildcard DNS record. Assuming ``myapps.com`` is the top-level
 
 Apps can then be accessed by browsers at ``appname.myapps.com``, and the controller will be available to the Deis client at ``deis.myapps.com``.
 
-This record is necessary for all deployments of Deis (EC2, Rackspace, DigitalOcean, Google Compute Engine, bare metal, etc.). Local clusters can use the domain ``local.deisapp.com``, ``local3.deisapp.com``, or ``local5.deiaspp.com``.
+This record is necessary for all deployments of Deis (EC2, Rackspace, DigitalOcean, Google Compute Engine, bare metal, etc.). Vagrant clusters can use the domain ``local.deisapp.com``, ``local3.deisapp.com``, or ``local5.deiaspp.com``.
 
 .. _xip_io:
 

docs/using_deis/deploy-application.rst

@@ -26,6 +26,10 @@ Before deploying an application, users must first authenticate against the Deis
     password:
     Logged in as deis
 
+.. note::
+
+    For Vagrant clusters: ``deis login http://deis.local3.deisapp.com``
+
 Select a Build Process
 ----------------------
 Deis supports three different ways of building applications:

docs/using_deis/register-user.rst

@@ -11,6 +11,9 @@ Register with a Controller
 Use ``deis register`` with the :ref:`Controller` URL (supplied by your Deis administrator)
 to create a new account.  You will be logged in automatically.
 
+The domain you use here should match the one you set with ``deisctl config platform set domain=``.
+Note that you always use ``deis.<domain>`` to communicate with the controller.
+
 .. code-block:: console
 
     $ deis register http://deis.example.com
@@ -21,6 +24,10 @@ to create a new account.  You will be logged in automatically.
     Registered myuser
     Logged in as myuser
 
+.. note::
+
+    For Vagrant clusters: ``deis register http://deis.local3.deisapp.com``
+
 .. important::
 
     The first user to register with Deis receives "superuser" privileges.
@@ -60,6 +67,10 @@ If you already have an account, use ``deis login`` to authenticate against the D
     password:
     Logged in as deis
 
+.. note::
+
+    For Vagrant clusters: ``deis login http://deis.local3.deisapp.com``
+
 .. note::
 
     Deis session information is stored in your user's ~/.deis directory.