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

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

.. _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-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``:

.. code-block:: ini

  [DEFAULT]
  development_mode = True

After, from the command line, execute:

.. code-block:: console

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

.. _development-utilities:

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

.. _Bandit: https://github.com/openstack/bandit

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.

.. _Alembic: http://alembic.zzzcomputing.com/en/latest/

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