openstack/deb-mistral
Code Issues Proposed changes

Mistral documentation: adding installation guide

Browse Source 
Implements blueprint mistral-docs-installation-guide

Change-Id: I7f84973b01a8ecf77b8b1adc16033d498f36e5aa
This commit is contained in:
Nikolay Mahotkin 2015-08-21 12:07:08 +03:00
parent 38d2609177
commit 1f7e359fb3
1 changed files with 117 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
doc/source/guides/installation_guide.rst
View File

@ -1,4 +1,120 @@
Mistral Installation Guide
==========================
TBD
Prerequisites
-------------
It is necessary to install some specific system libs for installing Mistral. They can be installed on most popular operating system using their package manager (for Ubuntu - *apt*, for Fedora, CentOS - *yum*, for Mac OS - *brew* or *macports*).
The list of needed packages is shown below:
1. **python-dev**
2. **python-setuptools**
3. **python-pip**
4. **libffi-dev**
5. **libxslt1-dev (or libxslt-dev)**
6. **libxml2-dev**
7. **libyaml-dev**
8. **libssl-dev**
In case of Ubuntu, just run::
apt-get install python-dev python-setuptools libffi-dev libxslt1-dev libxml2-dev libyaml-dev libssl-dev
**NOTE:** **Mistral can be used without authentication at all or it can work with OpenStack.** In case of OpenStack, it works **only on Keystone v3**, make sure **Keystone v3** is installed.
Installation
------------
**NOTE**: If it is needed to install Mistral using devstack, please refer to :doc:`Mistral Devstack Installation </developer/devstack>`
First of all, clone the repo and go to the repo directory::
git clone https://github.com/openstack/mistral.git
cd mistral
Generate config::
tox -egenconfig
Configure Mistral as needed. The configuration file is located in ``etc/mistral.conf``. For details see :doc:`Mistral Configuration Guide </guides/configuration_guide>`
**Virtualenv installation**::
tox
This will install necessary virtual environments and run all the project tests. Installing virtual environments may take significant time (~10-15 mins).
**Local installation**::
pip install -e .
or::
python setup.py install
**NOTE**: Differences *pip install -e* and *setup.py install*. **pip install -e** works very similarly to **setup.py install** or the EasyInstall tool, except that it doesn’t actually install anything. Instead, it creates a special .egg-link file in the deployment directory, that links to your project’s source code.
Before the first run
--------------------
After installation you will see **mistral-server** and **mistral-db-manage** commands in your environment, either in system or virtual environment.
**NOTE**: In case of using **virtualenv**, all Mistral related commands available via **tox -evenv --**. For example, *mistral-server* is available via *tox -evenv -- mistral-server*.
**mistral-db-manage** command can be used for migrations.
For updating the database to the latest revision type::
mistral-db-manage --config-file <path-to-mistral.conf> upgrade head
Before starting Mistral server, run *mistral-db-manage populate* command. It prepares the DB, creates in it with all standard actions and standard workflows which Mistral provides for all Mistral users.
::
mistral-db-manage --config-file <path-to-mistral.conf> populate
For more detailed information about *mistral-db-manage* script please see :doc:`Mistral Upgrade Guide </guides/upgrade_guide>`.
**NOTE**: For users who want a dry run with **SQLite** database backend(not used in production), *mistral-db-manage* is not recommended for database initialization because of `SQLite limitations <http://www.sqlite.org/omitted.html>`_. Please use sync_db script described below instead for database initilization.
**If you use virtualenv**::
tools/sync_db.sh --config-file <path-to-mistral.conf>
**Or run sync_db directly**::
python tools/sync_db.py --config-file <path-to-mistral.conf>
Running Mistral API server
--------------------------
To run Mistral API server perform the following command in a shell::
mistral-server --server api --config-file <path-to-mistral.conf>
Running Mistral Engines
-----------------------
To run Mistral Engine perform the following command in a shell::
mistral-server --server engine --config-file <path-to-mistral.conf>
Running Mistral Task Executors
------------------------------
To run Mistral Task Executor instance perform the following command in a shell::
mistral-server --server executor --config-file <path-to-mistral.conf>
Note that at least one Engine instance and one Executor instance should be running so that workflow tasks are processed by Mistral.
Running Multiple Mistral Servers Under the Same Process
-------------------------------------------------------
To run more than one server (API, Engine, or Task Executor) on the same process, perform the following command in a shell::
mistral-server --server api,engine --config-file <path-to-mistral.conf>
The --server command line option can be a comma delimited list. The valid options are "all" (by default if not specified) or any combination of "api", "engine", and "executor". It's important to note that the "fake" transport for the rpc_backend defined in the config file should only be used if "all" the Mistral servers are launched on the same process. Otherwise, messages do not get delivered if the Mistral servers are launched on different processes because the "fake" transport is using an in process queue.
Mistral Client Installation
---------------------------
Please refer to :doc:`Mistral Client / CLI Guide </guides/mistralclient_guide>`