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
This commit is contained in:
Felipe Monteiro
parent
e42ff5e8e3
commit
b96391dbbc
123
README.rst
123
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
|
||||
=================
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue