Felipe Monteiro c69f29e92f Revamp Deckhand documentation

This PS updates all Deckhand documentation to be
sphinx-compliant so that it can be rendered into
HTML automatically for hosting.

This PS also removes deprecated/redundant/unhelpful
documentation and upates README to a bit more
informative and helpful. The design.md file has been
broken up into different sections with deckhand/docs
for easier consumption.

Change-Id: I44afcd22a7f5f05e44563342bb98b30fd806f598

2017-10-16 20:11:56 +01:00

2.6 KiB

Raw Blame History

Deckhand

Deckhand is a document-based configuration storage service built with auditability and validation in mind.

Core Responsibilities

layering - helps reduce duplication in configuration while maintaining auditability across many sites
substitution - provides separation between secret data and other configuration data, while allowing a simple interface for clients
revision history - improves auditability and enables services to provide functional validation of a well-defined collection of documents that are meant to operate together
validation - allows services to implement and register different kinds of validations and report errors

Getting Started

To generate a configuration file automatically:

$ 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:

$ cp etc/deckhand/deckhand.conf.sample ~/deckhand.conf

To setup an in-memory database for testing:

[database]

#
# From oslo.db
#

# The SQLAlchemy connection string to use to connect to the database.
# (string value)
connection = sqlite:///:memory:

To run locally in a development environment:

$ sudo pip install uwsgi
$ virtualenv -p python3 /var/tmp/deckhand
$ . /var/tmp/deckhand/bin/activate
$ sudo pip install .
$ sudo python setup.py install
$ uwsgi --http :9000 -w deckhand.cmd --callable deckhand_callable --enable-threads -L

Testing

Automated Testing

To run unit tests using sqlite, execute:

$ tox -epy27
$ tox -epy35

against a py27- or py35-backed environment, respectively. To run individual unit tests, run:

$ tox -e py27 -- deckhand.tests.unit.db.test_revisions

for example.

To run unit tests using postgresql, execute:

$ tox -epy27-postgresql
$ tox -epy35-postgresql

To run functional tests:

$ tox -e functional

You can also run a subset of tests via a regex:

$ tox -e functional -- gabbi.suitemaker.test_gabbi_document-crud-success-multi-bucket

Manual Testing

Document creation can be tested locally using (from root deckhand directory):

$ curl -i -X PUT localhost:9000/api/v1.0/bucket/{bucket_name}/documents \
     -H "Content-Type: application/x-yaml" \
     --data-binary "@deckhand/tests/unit/resources/sample_document.yaml"

# revision_id copy/pasted from previous response.
$ curl -i -X GET localhost:9000/api/v1.0/revisions/1

2.6 KiB Raw Blame History