..
      Licensed under the Apache License, Version 2.0 (the "License"); you may
      not use this file except in compliance with the License. You may obtain
      a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
      License for the specific language governing permissions and limitations
      under the License.

==================
Installing Watcher
==================

This document describes how to install Watcher in order to use it. If you are
intending to develop on or with Watcher, please read :doc:`../dev/environment`.

Prerequisites
-------------

The source install instructions specifically avoid using platform specific
packages, instead using the source for the code and the Python Package Index
(PyPi_).

.. _PyPi: http://pypi.python.org/pypi

It's expected that your system already has python2.7_, latest version of pip_,
and git_ available.

.. _python2.7: http://www.python.org
.. _pip: http://www.pip-installer.org/en/latest/installing.html
.. _git: http://git-scm.com/

Your system shall also have some additional system libraries:

  On Ubuntu (tested on 14.04LTS):

  .. code-block:: bash

    $ sudo apt-get install python-dev libssl-dev libmysqlclient-dev libffi-dev

  On Fedora-based distributions e.g., Fedora/RHEL/CentOS/Scientific Linux
  (tested on CentOS 7.1):

  .. code-block:: bash

    $ sudo yum install gcc python-devel openssl-devel libffi-devel mysql-devel


Installing from Source
----------------------

Clone the Watcher repository:

.. code-block:: bash

    $ git clone https://git.openstack.org/openstack/watcher.git
    $ cd watcher

Install the Watcher modules:

.. code-block:: bash

    # python setup.py install

The following commands should be available on the command-line path:

* ``watcher-api`` the Watcher Web service used to handle RESTful requests
* ``watcher-decision-engine`` the Watcher Decision Engine used to build action
  plans, according to optimization goals to achieve.
* ``watcher-applier`` the Watcher Applier module, used to apply action plan
* ``watcher-db-manage`` used to bootstrap Watcher data

You will find sample configuration files in ``etc/watcher``:

* ``watcher.conf.sample``

Install the Watcher modules dependencies:

.. code-block:: bash

    # pip install -r requirements.txt

From here, refer to :doc:`configuration` to declare Watcher as a new service
into Keystone and to configure its different modules. Once configured, you
should be able to run the Watcher services by issuing these commands:

.. code-block:: bash

    $ watcher-api
    $ watcher-decision-engine
    $ watcher-applier

By default, this will show logging on the console from which it was started.
Once started, you can use the `Watcher Client`_ to play with Watcher service.

.. _`Watcher Client`: https://git.openstack.org/openstack/python-watcherclient.git

Installing from packages: PyPI
--------------------------------

Watcher package is available on PyPI repository. To install Watcher on your
system:

.. code-block:: bash

    $ sudo pip install python-watcher

The Watcher services along with its dependencies should then be automatically
installed on your system.

Once installed, you still need to declare Watcher as a new service into
Keystone and to configure its different modules, which you can find described
in :doc:`configuration`.