deckhand/docs/source/getting-started.rst

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

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

[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

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 DECKHAND_CONFIG_DIR=<PATH>
$ [sudo] cp etc/deckhand/deckhand.conf.sample ${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 ${DECKHAND_CONFIG_DIR}:

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

$ chmod +x entrypoint.sh
$ ./entrypoint.sh

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

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