From b96391dbbcced9872c2913c721b28bb8b4693c5e Mon Sep 17 00:00:00 2001
From: Felipe Monteiro <felipe.monteiro@att.com>
Date: Fri, 26 Jan 2018 20:03:56 +0000
Subject: [PATCH] Update Deckhand README

Part of the README is out of date and needs to be updated. The
Getting Started section was also updated to contain information
about how to run Deckhand via Docker as well as how to do a
complete manual install of Deckhand.

The testing documentation was also updated because some tox
jobs have been removed, so the commands in the README should too.

Change-Id: I4438d3b3462e06923969831242cb377237c03480
---
 README.rst | 123 +++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 105 insertions(+), 18 deletions(-)

diff --git a/README.rst b/README.rst
index 858a2934..6c84ed4d 100644
--- a/README.rst
+++ b/README.rst
@@ -23,18 +23,45 @@ Core Responsibilities
 Getting Started
 ===============
 
-To generate a configuration file automatically::
+Pre-requisites
+--------------
+
+* tox
+
+  To install tox run::
+
+    $ sudo apt-get install tox
+
+* PostgreSQL
+
+  Deckhand only supports PostgreSQL. Install it by running::
+
+    $ sudo apt-get update
+    $ sudo apt-get install postgresql postgresql-contrib
+
+Quick Start
+-----------
+
+`Docker`_ can be used to quickly instantiate the Deckhand image. After
+installing `Docker`_, create a basic configuration file::
 
     $ tox -e genconfig
 
 Resulting deckhand.conf.sample file is output to
 :path:etc/deckhand/deckhand.conf.sample
 
-Copy the config file to a directory discoverably by ``oslo.conf``::
+Move the sample configuration file into a desired directory
+(i.e. ``$CONF_DIR``).
 
-    $ cp etc/deckhand/deckhand.conf.sample ~/deckhand.conf
+At a minimum the ``[database].connection`` config option must be set.
+Provide it with a PostgreSQL database connection. Or to conveniently create an
+ephemeral PostgreSQL DB run::
 
-To setup an in-memory database for testing:
+    $ eval `pifpaf run postgresql`
+
+Substitute the connection information (which can be retrieved by running
+``export | grep PIFPAF_POSTGRESQL_URL``) into the config file inside
+``etc/deckhand/deckhand.conf.sample``::
 
 .. code-block:: ini
 
@@ -46,16 +73,85 @@ To setup an in-memory database for testing:
 
     # The SQLAlchemy connection string to use to connect to the database.
     # (string value)
-    connection = sqlite:///:memory:
+    connection = postgresql://localhost/postgres?host=/tmp/tmpsg6tn3l9&port=9824
 
-To run locally in a development environment::
+Finally, run Deckhand::
+
+    $ [sudo] docker run --rm \
+        --net=host \
+        -p 9000:9000 \
+        -v $CONF_DIR:/etc/deckhand
+        quay.io/attcomdev/deckhand:latest
+
+To kill the ephemeral DB afterward::
+
+    $ pifpaf_stop
+
+.. _Docker: https://docs.docker.com/install/
+
+Manual Installation
+-------------------
+
+.. note::
+
+    The commands below assume that they are being executed from the root
+    Deckhand directory.
+
+Install dependencies needed to spin up Deckhand via ``uwsgi``::
 
     $ sudo pip install uwsgi
     $ virtualenv -p python3 /var/tmp/deckhand
     $ . /var/tmp/deckhand/bin/activate
-    $ sudo pip install .
-    $ sudo python setup.py install
-    $ uwsgi --ini uwsgi.ini
+    $ pip install -r requirements.txt test-requirements.txt
+    $ python setup.py install
+
+Afterward, create a sample configuration file automatically::
+
+    $ tox -e genconfig
+
+Resulting deckhand.conf.sample file is output to
+:path:etc/deckhand/deckhand.conf.sample
+
+Create the directory ``/etc/deckhand`` and copy the config file there::
+
+    $ [sudo] cp etc/deckhand/deckhand.conf.sample /etc/deckhand/deckhand.conf
+
+To specify an alternative directory for the config file, run::
+
+    $ export OS_DECKHAND_CONFIG_DIR=<PATH>
+    $ [sudo] cp etc/deckhand/deckhand.conf.sample ${OS_DECKHAND_CONFIG_DIR}/deckhand.conf
+
+To conveniently create an ephemeral PostgreSQL DB run::
+
+    $ eval `pifpaf run postgresql`
+
+Retrieve the environment variable which contains connection information::
+
+    $ export | grep PIFPAF_POSTGRESQL_URL
+    declare -x PIFPAF_POSTGRESQL_URL="postgresql://localhost/postgres?host=/tmp/tmpsg6tn3l9&port=9824"
+
+Substitute the connection information into the config file in
+``${OS_DECKHAND_CONFIG_DIR}``::
+
+.. code-block:: ini
+
+    [database]
+
+    #
+    # From oslo.db
+    #
+
+    # The SQLAlchemy connection string to use to connect to the database.
+    # (string value)
+    connection = postgresql://localhost/postgres?host=/tmp/tmpsg6tn3l9&port=9824
+
+Finally, run Deckhand::
+
+    $ uwsgi --ini wsgi.ini
+
+To kill the ephemeral DB afterward::
+
+    $ pifpaf_stop
 
 Testing
 -------
@@ -79,14 +175,6 @@ unit tests, run:
 
 for example.
 
-To run unit tests using postgresql, postgresql must be installed in your
-environment. Then execute:
-
-::
-
-    $ tox -epy27-postgresql
-    $ tox -epy35-postgresql
-
 To run functional tests:
 
 ::
@@ -99,7 +187,6 @@ You can also run a subset of tests via a regex:
 
     $ tox -e functional -- gabbi.suitemaker.test_gabbi_document-crud-success-multi-bucket
 
-
 Intgration Points
 =================