From 3c8a65a8135e594f2c210d01ee1673fc0b3e4303 Mon Sep 17 00:00:00 2001 From: Felipe Monteiro Date: Thu, 15 Feb 2018 19:49:30 +0000 Subject: [PATCH] Docs: Update README and create Getting Started docs Update the README by moving a lot of the manual installation into Getting Started docs and simplify some of the documentation because Deckhand can be re-run using sqlite (for dev purposes, for example). Change-Id: I5742dc75b95e2af67a18b419d04e769c10a1e43e --- AUTHORS | 1 + README.rst | 132 +---------------- doc/source/getting-started.rst | 253 +++++++++++++++++++++++++++++++++ doc/source/index.rst | 1 + 4 files changed, 258 insertions(+), 129 deletions(-) create mode 100644 doc/source/getting-started.rst diff --git a/AUTHORS b/AUTHORS index 32272823..1d33c9a4 100644 --- a/AUTHORS +++ b/AUTHORS @@ -4,6 +4,7 @@ Bryan Strassner Felipe Monteiro Felipe Monteiro Kochetov, Mikhail (mk899x) +Krysta Mark Burnett Mike Kochetov Pete Birley diff --git a/README.rst b/README.rst index 6c84ed4d..1ad5cebc 100644 --- a/README.rst +++ b/README.rst @@ -23,135 +23,9 @@ Core Responsibilities Getting Started =============== -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 - -Move the sample configuration file into a desired directory -(i.e. ``$CONF_DIR``). - -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:: - - $ 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 - - [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:: - - $ [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 - $ 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= - $ [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 +For more detailed installation and setup information, please refer to the +`Getting Started `_ +guide. Testing ------- diff --git a/doc/source/getting-started.rst b/doc/source/getting-started.rst new file mode 100644 index 00000000..b8ad71d3 --- /dev/null +++ b/doc/source/getting-started.rst @@ -0,0 +1,253 @@ +Getting Started +=============== + +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 + +Quickstart +---------- + +SQLite +^^^^^^ + +The guide below provides details on how to run Deckhand quickly using +SQLite. + +`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 + +Move the sample configuration file into a desired directory +(i.e. ``$CONF_DIR``). + +Set the database string in the configuration file to ``sqlite://`` + +:: + + .. code-block:: ini + + [database] + + # + # From oslo.db + # + + # The SQLAlchemy connection string to use to connect to the database. + # (string value) + connection = sqlite:// + +Finally, run Deckhand via Docker:: + + $ [sudo] docker run --rm \ + --net=host \ + -p 9000:9000 \ + -v $CONF_DIR:/etc/deckhand \ + quay.io/attcomdev/deckhand:latest + +PostgreSQL +^^^^^^^^^^ + +The guide below provides details on how to run Deckhand quickly using +PostgreSQL. + +`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 + +Move the sample configuration file into a desired directory +(i.e. ``$CONF_DIR``). + +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:: + + $ 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 + + [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 via Docker:: + + $ [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 + $ pip install -r requirements.txt -r 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= + $ [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 + +Development Utilities +--------------------- + +Deckhand comes equipped with many utilities useful for developers, such as +unit test or linting jobs. + +Many of these commands require that ``tox`` be installed. To do so, run:: + + $ pip3 install tox + +To run the Python linter, execute:: + + $ tox -e pep8 + +To run unit tests, execute:: + + $ tox -e py35 + +To run the test coverage job:: + + $ tox -e coverage + +To run security checks via `Bandit`_ execute:: + + $ tox -e bandit + +To build all Deckhand charts, execute:: + + $ make charts + +To generate sample configuration and policy files needed for Deckhand +deployment, execute (respectively):: + + $ tox -e genconfig + $ tox -e genpolicy + +.. _Bandit: https://github.com/openstack/bandit + +Troubleshooting +--------------- + +The error messages are included in bullets below and tips to resolution are +included beneath each bullet. + +* "FileNotFoundError: [Errno 2] No such file or directory: '/etc/deckhand/api-paste.ini'" + + Reason: this means that Deckhand is trying to instantiate the server but + failing to do so because it can't find an essential configuration file. + + Solution:: + + $ cp etc/deckhand/deckhand.conf.sample /etc/deckhand/deckhand.conf + + This copies the sample Deckhand configuration file to the appropriate + directory. + +* For any errors related to ``tox``: + + Ensure that ``tox`` is installed:: + + $ [sudo] apt-get install tox -y + +* For any errors related to running ``tox -e py35``: + + Ensure that ``python3-dev`` is installed:: + + $ [sudo] apt-get install python3-dev -y + +* For any errors related to running ``tox -e py27``: + + Ensure that ``python3-dev`` is installed:: + + $ [sudo] apt-get install python-dev -y diff --git a/doc/source/index.rst b/doc/source/index.rst index 9d3b15be..13dd6496 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -38,6 +38,7 @@ User's Guide .. toctree:: :maxdepth: 2 + getting-started overview documents document_types