From efe0c652c01101ff41359a53818ecd613f9d7da8 Mon Sep 17 00:00:00 2001 From: Philip Jenvey Date: Thu, 28 Jul 2016 16:03:08 -0700 Subject: [PATCH] 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 | 2 +- docs/running.rst | 74 +++++++++++++++++++++++++++++++++++++----------- 2 files changed, 58 insertions(+), 18 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index b2463d02..4d7a87fe 100644 --- a/docs/install.rst +++ b/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 `_. Be sure to `properly set up `_ your ``.boto`` configuration file. +Autopush uses the `Boto python library `_. Be sure to `properly set up `_ your boto configuration file. Python 2.7.7+ w/virtualenv ========================== diff --git a/docs/running.rst b/docs/running.rst index cd2b28f6..6e6f0c98 100644 --- a/docs/running.rst +++ b/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 -`_ -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 = + $ cp configs/autopush_shared.ini . + +Then edit your ``autopush_shared.ini`` to include it: + +.. code-block:: ini + + crypto_key = [] + +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