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
This commit is contained in:
Felipe Monteiro
Bryan Strassner
parent
b81cebb012
commit
3c8a65a813
1
AUTHORS
1
AUTHORS
@ -4,6 +4,7 @@ Bryan Strassner <bryan.strassner@gmail.com>
|
||||
Felipe Monteiro <felipe.monteiro@att.com>
|
||||
Felipe Monteiro <fmontei@users.noreply.github.com>
|
||||
Kochetov, Mikhail (mk899x) <mk899x@us.att.com>
|
||||
Krysta <klknight23@gmail.com>
|
||||
Mark Burnett <mark.m.burnett@gmail.com>
|
||||
Mike Kochetov <mike.nycmoma@gmail.com>
|
||||
Pete Birley <pete@port.direct>
|
||||
|
||||
132
README.rst
132
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=<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
|
||||
For more detailed installation and setup information, please refer to the
|
||||
`Getting Started <http://deckhand.readthedocs.io/en/latest/getting-started.html>`_
|
||||
guide.
|
||||
|
||||
Testing
|
||||
-------
|
||||
|
||||
253
doc/source/getting-started.rst
Normal file
253
doc/source/getting-started.rst
Normal file
@ -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=<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
|
||||
|
||||
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
|
||||
@ -38,6 +38,7 @@ User's Guide
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
getting-started
|
||||
overview
|
||||
documents
|
||||
document_types
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user