Reproduce CI jobs for debugging and development
===============================================

Reproducing any given CI job that is executed upstream is critical for
development.  You will find a script called "reproducer-quickstart.sh" under
the logs directory of any TripleO CI job that will assist you in recreating a
TripleO Quickstart upstream job.

Each script contains the same parameters used in the job and includes any
deployment or CI related settings.  Any patches that were marked as
dependencies will also be included in the script and execution.

This script will provision a heat stack in an OpenStack host cloud that matches
the environment created by nodepool or `OVB <http://openstack-virtual-baremetal.
readthedocs.io/en/latest/introduction.html>`_ upstream.  Once the environment
is ready, the script prompts the user with some additional instructions that
executes the same scripts and tools used upstream to bootstrap and execute the
CI.

Install system dependencies
---------------------------
Before execute the reproduce-quickstart it's necessary to install few
dependencies on the system::

* pip
* virtualenv
* ansible
* python-openstackclient
* python-heatclient

How to execute the reproducer-quickstart script
-----------------------------------------------

Go to the "logs" directory of the job::

    wget http://logs.openstack.org/07/472607/<snip>/f98d674/logs/reproducer-quickstart.sh

Be sure you have download the OpenStack RC file. To have more information you
can check the documentation `here <https://docs.openstack.org/newton/user-guide
/common/cli-set-environment-variables-using-openstack-rc.html>`_.

Source your OpenStack RC file::

    source openstack_rc.sh

Execute the reproducer-quickstart.sh::

    bash -x reproducer-quickstart.sh

The following additional options are recommended::

    bash -x reproducer-quickstart.sh --workspace /var/tmp/reproduce \
    --create-virtualenv true --remove-stacks-keypairs true \
    --nodestack-prefix repro

Please check the script's help command however the available options are::


  Options:
  -w, --workspace <dir>
                      directory where the virtualenv, inventory files, etc.
                      are created. Defaults to creating a directory in /tmp
  -v, --create-virtualenv
                      create a virtualenv to install Ansible and dependencies.
                      Options to pass true/false. Defaults to true for OVB.
                      Defaults to false for other deployment types.
  -r, --remove-stacks-keypairs
                      delete all Heat stacks (both Multinode and OVB created)
                      in the tenant before deployment.
                      Will also delete associated keypairs if they exist.
                      Options to pass true/false.Defaults to false.
  -p, --nodestack-prefix
                      add a unique prefix for multinode and singlenode stacks
                      Defaults to empty.
  -a, --autorun
                      Run job on prepared environment automatically
                      Default is to stop after environment is ready
  -h, --help          print this help and exit

How does this script work
-------------------------

The script is generated by a `jinja2 template <https://github.com/openstack/
tripleo-quickstart-extras/blob/master/roles/create-reproducer-script/templates/
reproducer-quickstart.sh.j2>`_ that reads all the variables passed to the CI job
and builds a custom script for each job.  There are two major steps to be
familiar with in this script.  The first part of the script will provision the
servers, networks and other infrastructure for the TripleO deployment.  The
second part invokes the CI tools and scripts in the `same way the original CI
job was executed <https://github.com/openstack-infra/tripleo-ci/blob/master/
toci_gate_test-oooq.sh>`_.

Notes
-----

If the environment was provisioned successfully you will be presented with
further instructions that will prompt you to ssh to the environment and execute
the upstream CI scripts.  You may elect to run this automatically with the
"autorun" option found in the help.

Support
-------

The TripleO CI team will provide community support for the
reproducer-quickstart.sh script.  The tool is only supported in use with an
OpenStack host cloud.  Your results with various OpenStack providers may vary.
Please open any issues or problems in
`launchpad <https://bugs.launchpad.net/tripleo>`_ with the "quickstart" tag.

The `devmode.sh <https://github.com/openstack/tripleo-quickstart/blob/master/
devmode.sh>`_ script is deprecated.  The reproducer-quickstart.sh should be
used for upstream development and debugging of TripleO CI.