docs: updates to intros

* mention the other cli tools, in particular autokey
* suggest BOTO_CONFIG vs ~/.boto which potentially clashes with test running

issue #565

docs/install.rst

@@ -33,7 +33,7 @@ For instance, if installing on an Amazon EC2 machine:
     libncurses5-devel openssl-devel patch python-devel \
     python-virtualenv readline-devel -y
 
-Autopush uses the `Boto python library <https://boto.readthedocs.io/en/latest/>`_. Be sure to `properly set up <https://boto.readthedocs.io/en/latest/boto_config_tut.html>`_ your ``.boto`` configuration file.
+Autopush uses the `Boto python library <https://boto.readthedocs.io/en/latest/>`_. Be sure to `properly set up <https://boto.readthedocs.io/en/latest/boto_config_tut.html>`_ your boto configuration file.
 
 Python 2.7.7+ w/virtualenv
 ==========================

docs/running.rst

@@ -4,25 +4,25 @@
 Running Autopush
 ================
 
-There are two programs that will have scripts setup after installing (In the
-``pypy/bin/`` directory):
+After installation of autopush the following command line utilities are
+available in the ``bin/`` directory:
 
-- ``autopush``
-- ``autoendpoint``
+=======================    ===========
+``autopush``               Runs a Connection Node
+``autoendpoint``           Runs an Endpoint Node
+``endpoint_diagnostic``    Runs Endpoint diagnostics
+``autokey``                Endpoint encryption key generator
+=======================    ===========
 
-You will need to have a ``~/.boto`` file or ``AWS`` environment keys setup
-before either of these will run properly. By default they will create a router
-and storage DynamoDB table named ``storage`` and ``router`` with provisioned
-throughputs of ``5``.
+You will need to have a `boto config file`_ file or ``AWS`` environment keys
+setup before the first 3 utilities will run properly.
 
 Using a Local DynamoDB Server
 =============================
 
-Amazon supplies a `Local DynamoDB Java server
-<http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Tools.DynamoDBLocal.html>`_
-to use for local testing that implements the complete DynamoDB API. This is used
-for automated unit testing on Travis and can be used to run autopush locally for
-testing.
+Amazon supplies a `Local DynamoDB Java server`_ to use for local testing that
+implements the complete DynamoDB API. This is used for automated unit testing
+on Travis and can be used to run autopush locally for testing.
 
 You will need the Java JDK 6.x or newer.
 
@@ -33,8 +33,48 @@ To setup the server locally:
     $ mkdir ddb
     $ curl -sSL http://dynamodb-local.s3-website-us-west-2.amazonaws.com/dynamodb_local_latest.tar.gz | tar xzvC ddb/
     $ java -Djava.library.path=./ddb/DynamoDBLocal_lib -jar ./ddb/DynamoDBLocal.jar -sharedDb -inMemory
-    $ cp automock/boto.cfg ~/.boto
 
-Note the last line copies a boto config over ``~/.boto`` in your home dir. If
-you have existing AWS Credentials in this file, you should move it elsewhere
-first before running ``autopush`` and ``autoendpoint``.
+An example `boto config file`_ is provided in ``automock/boto.cfg`` that
+directs autopush to your local DynamoDB instance.
+
+Configuring the Nodes
+=====================
+
+Besides DynamoDB, at a bare minimum, autopush requires configuration of a token
+encryption key generated by the ``autokey`` program. This key should be shared
+by Connection and Endpoint nodes in the same cluster.
+
+To generate and configure a key:
+
+.. code-block:: bash
+
+    $ bin/autokey
+    Key = <crypto key here>
+    $ cp configs/autopush_shared.ini .
+
+Then edit your ``autopush_shared.ini`` to include it:
+
+.. code-block:: ini
+
+    crypto_key = [<paste crypto key here>]
+
+You may also want to enable human readable logs in the shared config file:
+
+.. code-block:: ini
+
+    ; Uncomment to provide stdout logging in a more human readable format.
+    #human_logs
+
+Running the nodes
+=================
+
+.. code-block:: bash
+
+    $ BOTO_CONFIG=automock/boto.cfg bin/autopush --config-shared=./autopush_shared.ini
+    $ BOTO_CONFIG=automock/boto.cfg bin/autoendpoint --config-shared=./autopush_shared.ini
+
+By default they will create a router and storage DynamoDB table named
+``storage`` and ``router`` with provisioned throughputs of ``5``.
+
+.. _`Local DynamoDB Java server`: http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Tools.DynamoDBLocal.html
+.. _`boto config file`: https://boto.readthedocs.io/en/latest/boto_config_tut.html