deckhand/doc/source/users/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/airshipit/deckhand:latest-ubuntu_bionic

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

Run an update to the Database to bring it to the current code level:

$ [sudo] docker run --rm \
    --net=host \
    -v $CONF_DIR:/etc/deckhand \
    quay.io/airshipit/deckhand:latest-ubuntu_bionic\
    alembic upgrade head

Finally, run Deckhand via Docker:

$ [sudo] docker run --rm \
    --net=host \
    -p 9000:9000 \
    -v $CONF_DIR:/etc/deckhand \
    quay.io/airshipit/deckhand:latest-ubuntu_bionic

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-frozen.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:

# Perform DB migrations
$ ./entrypoint.sh alembic upgrade head
# Instantiate the Deckhand server
$ ./entrypoint.sh server

To kill the ephemeral DB afterward:

$ pifpaf_stop

Development Mode

Development mode means running Deckhand without Keystone authentication. Note that enabling development mode will effectively disable all authN and authZ in Deckhand.

To enable development mode, add the following to the deckhand.conf inside $CONF_DIR:

[DEFAULT]
development_mode = True

After, from the command line, execute:

$ [sudo] docker run --rm \
    --net=host \
    -p 9000:9000 \
    -v $CONF_DIR:/etc/deckhand \
    quay.io/airshipit/deckhand:latest-ubuntu_bionic server

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 py36

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

For additional commands, reference the tox.ini file for a list of all the jobs.

Database Model Updates

Deckhand utilizes Alembic to handle database setup and upgrades. Alembic provides a straightforward way to manage the migrations necessary from one database structure version to another through the use of scripts found in deckhand/alembic/versions.

Setting up a migration can be automatic or manual. The Alembic documentation provides instructions for how to create a new migration.

Creating automatic migrations requires that the Deckhand database model is updated in the source code first. With that database model in the code, and pointing to an existing Deckhand database structure, Alembic can produce the steps necessary to move from the current version to the next version.

One way of creating an automatic migration is to deploy a development Deckhand database using the pre-updated data model and following the following steps:

Navigate to the root Deckhand directory
$ export DH_ROOT=$(pwd)
$ mkdir ${DH_ROOT}/alembic_tmp

Create a deckhand.conf file that will have the correct DB connection string.
$ tox -e genconfig
$ cp ${DH_ROOT}/etc/deckhand/deckhand.conf.sample ${DH_ROOT}/alembic_tmp/deckhand.conf

Update the connection string to the deckhand db instance e.g.::

  [Database]
  connection = postgresql+psycopg2://deckhand:password@postgresql.airship.svc.cluster.local:5432/deckhand

$ export DECKHAND_CONFIG_DIR=${DH_ROOT}/alembic_tmp
$ alembic revision --autogenerate -m "The short description for this change"

$ rm -r ${DH_ROOT}/alembic_tmp

This will create a new .py file in the deckhand/alembic/versions directory that can then be modified to indicate exact steps. The generated migration should always be inspected to ensure correctness.

Migrations exist in a linked list of files (the files in versions). Each file is updated by Alembic to reference its revision linkage. E.g.:

# revision identifiers, used by Alembic.
revision = '918bbfd28185'
down_revision = None
branch_labels = None
depends_on = None

Any manual changes to this linkage must be approached carefully or Alembic will fail to operate.

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

  Ensure that python3-dev is installed:

  $ [sudo] apt-get install python3-dev -y