Lingxian Kong
5 years ago
10 changed files with 205 additions and 167 deletions
@ -0,0 +1,27 @@
|
||||
======================== |
||||
Qinling Development Docs |
||||
======================== |
||||
|
||||
Files under this directory tree are used for generating the documentation |
||||
for the qinling source code. |
||||
|
||||
Developer documentation is built to: |
||||
http://qinling.readthedocs.io/en/latest/ |
||||
|
||||
Tools |
||||
===== |
||||
|
||||
Sphinx |
||||
The Python Sphinx package is used to generate the documentation output. |
||||
Information on Sphinx, including formatting information for RST source |
||||
files, can be found in the `Sphinx online documentation |
||||
<http://www.sphinx-doc.org/en/stable/>`_. |
||||
|
||||
Building Documentation |
||||
====================== |
||||
|
||||
Doc builds are performed using tox with the ``docs`` target:: |
||||
|
||||
% cd .. |
||||
% tox -e docs |
||||
|
||||
@ -1,4 +1,4 @@
|
||||
============ |
||||
Contributing |
||||
============ |
||||
.. include:: ../../CONTRIBUTING.rst |
||||
.. include:: ../../../CONTRIBUTING.rst |
||||
@ -0,0 +1,109 @@
|
||||
.. |
||||
Copyright 2017 Catalyst IT Ltd |
||||
All Rights Reserved. |
||||
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. |
||||
|
||||
Setting up a development environment with devstack |
||||
================================================== |
||||
|
||||
This page describes how to setup a working development |
||||
environment that can be used in deploying qinling on latest releases |
||||
of Ubuntu. These instructions assume you are already familiar |
||||
with git. Refer to `Getting the code`_ for additional information. |
||||
|
||||
.. _Getting the code: http://wiki.openstack.org/GettingTheCode |
||||
|
||||
Following these instructions will allow you to have a fully functional qinling |
||||
environment using the devstack project (a shell script to build |
||||
complete OpenStack development environments) on Ubuntu 16.04. |
||||
|
||||
Configuring devstack with qinling |
||||
--------------------------------- |
||||
|
||||
Qinling can be enabled in devstack by using the plug-in based interface it |
||||
offers. |
||||
|
||||
.. note:: |
||||
|
||||
The following steps have been fully verified only on Ubuntu 16.04. |
||||
|
||||
Start by cloning the devstack repository: |
||||
|
||||
:: |
||||
|
||||
git clone https://github.com/openstack-dev/devstack |
||||
|
||||
Change to devstack directory: |
||||
|
||||
:: |
||||
|
||||
cd devstack/ |
||||
|
||||
Copy the ``local.conf`` sample file to the upper level directory: |
||||
|
||||
:: |
||||
|
||||
cp samples/local.conf . |
||||
|
||||
Enable the qinling plugin adding the following lines to the end of the |
||||
``local.conf`` file: |
||||
|
||||
:: |
||||
|
||||
ENABLED_SERVICES=rabbit,mysql,key,tempest |
||||
enable_plugin qinling https://github.com/openstack/qinling |
||||
LIBS_FROM_GIT="python-qinlingclient" |
||||
|
||||
Running devstack |
||||
---------------- |
||||
|
||||
.. note:: |
||||
|
||||
Before running devstack, make sure there is a loopback device defined in |
||||
``/etc/hosts`` file, ``127.0.1.1 localhost`` is recommended, any line |
||||
including '127.0.0.1' will be deleted automatically during devstack running. |
||||
|
||||
Run the ``stack.sh`` script: |
||||
|
||||
:: |
||||
|
||||
./stack.sh |
||||
|
||||
After it completes, verify qinling service is installed properly: |
||||
|
||||
.. code-block:: console |
||||
|
||||
$ source openrc admin admin |
||||
$ openstack service list |
||||
+----------------------------------+----------+----------+ |
||||
| ID | Name | Type | |
||||
+----------------------------------+----------+----------+ |
||||
| 60145bf464f943aa88613026bd6aa5e3 | qinling | function | |
||||
| 750ec7b067b7465bab2389e331f826de | keystone | identity | |
||||
+----------------------------------+----------+----------+ |
||||
$ openstack runtime list --print-empty |
||||
+----+------+-------+--------+-------------+------------+------------+------------+ |
||||
| Id | Name | Image | Status | Description | Project_id | Created_at | Updated_at | |
||||
+----+------+-------+--------+-------------+------------+------------+------------+ |
||||
+----+------+-------+--------+-------------+------------+------------+------------+ |
||||
|
||||
Kubernetes Integration |
||||
---------------------- |
||||
|
||||
By default, Qinling uses Kubernetes as its orchestrator backend, so a k8s |
||||
all-in-one environment (and some other related tools, e.g. kubectl) is also |
||||
setup during devstack installation. |
||||
|
||||
The idea and most of the scripts are coming from |
||||
`OpenStack-Helm <http://openstack-helm.readthedocs.io/en/latest/index.html>`_ |
||||
project originally, but may be probably changed as the project evolving in |
||||
future. |
||||
@ -0,0 +1,37 @@
|
||||
.. |
||||
Copyright 2010-2011 United States Government as represented by the |
||||
Administrator of the National Aeronautics and Space Administration. |
||||
All Rights Reserved. |
||||
|
||||
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. |
||||
|
||||
Contributor/Developer Guide |
||||
=========================== |
||||
|
||||
In this section you will find information helpful for contributing to qinling |
||||
project. |
||||
|
||||
|
||||
Programming HowTos and Tutorials |
||||
-------------------------------- |
||||
.. toctree:: |
||||
:maxdepth: 2 |
||||
|
||||
development-environment-devstack |
||||
contributing |
||||
|
||||
Indices and tables |
||||
------------------ |
||||
|
||||
* :ref:`genindex` |
||||
* :ref:`search` |
||||
@ -1,148 +0,0 @@
|
||||
Qinling Installation Guide |
||||
========================== |
||||
|
||||
Prerequisites |
||||
~~~~~~~~~~~~~ |
||||
|
||||
It is necessary to install some specific system libs for installing Qinling. |
||||
They can be installed on most popular operating system using their package |
||||
manager (for Ubuntu - *apt*, for Fedora - *dnf*, 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 -y python-dev python-setuptools python-pip libffi-dev libxslt1-dev \ |
||||
libxml2-dev libyaml-dev libssl-dev |
||||
|
||||
**NOTE:** **Qinling 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 |
||||
~~~~~~~~~~~~ |
||||
|
||||
First of all, clone the repo and go to the repo directory:: |
||||
|
||||
$ git clone https://github.com/openstack/qinling.git |
||||
$ cd qinling |
||||
|
||||
Generate config:: |
||||
|
||||
$ tox -egenconfig |
||||
|
||||
Configure Qinling as needed. The configuration file is located in |
||||
``etc/qinling.conf.sample``. You will need to modify the configuration options |
||||
and then copy it into ``/etc/qinling/qinling.conf``. |
||||
For details see :doc:`Qinling 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:: |
||||
|
||||
$ pip install -r requirements.txt |
||||
$ 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 **qinling-server** and **qinling-db-manage** commands |
||||
in your environment, either in system or virtual environment. |
||||
|
||||
**NOTE**: In case of using **virtualenv**, all Qinling related commands available via |
||||
**tox -evenv --**. For example, *qinling-server* is available via |
||||
*tox -evenv -- qinling-server*. |
||||
|
||||
**qinling-db-manage** command can be used for migrations. |
||||
|
||||
For updating the database to the latest revision type:: |
||||
|
||||
$ qinling-db-manage --config-file <path-to-qinling.conf> upgrade head |
||||
|
||||
Before starting Qinling server, run *qinling-db-manage populate* command. |
||||
It prepares the DB, creates in it with all standard actions and standard |
||||
workflows which Qinling provides for all Qinling users.:: |
||||
|
||||
$ qinling-db-manage --config-file <path-to-qinling.conf> populate |
||||
|
||||
For more detailed information about *qinling-db-manage* script please see :doc:`Qinling Upgrade Guide </guides/upgrade_guide>`. |
||||
|
||||
**NOTE**: For users who want a dry run with **SQLite** database backend(not |
||||
used in production), *qinling-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 initialization. |
||||
|
||||
**If you use virtualenv**:: |
||||
|
||||
$ tools/sync_db.sh --config-file <path-to-qinling.conf> |
||||
|
||||
**Or run sync_db directly**:: |
||||
|
||||
$ python tools/sync_db.py --config-file <path-to-qinling.conf> |
||||
|
||||
Running Qinling API server |
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~ |
||||
|
||||
To run Qinling API server perform the following command in a shell:: |
||||
|
||||
$ qinling-server --server api --config-file <path-to-qinling.conf> |
||||
|
||||
Running Qinling Engines |
||||
~~~~~~~~~~~~~~~~~~~~~~~ |
||||
|
||||
To run Qinling Engine perform the following command in a shell:: |
||||
|
||||
$ qinling-server --server engine --config-file <path-to-qinling.conf> |
||||
|
||||
Running Qinling Task Executors |
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
||||
To run Qinling Task Executor instance perform the following command in a shell:: |
||||
|
||||
$ qinling-server --server executor --config-file <path-to-qinling.conf> |
||||
|
||||
Note that at least one Engine instance and one Executor instance should be |
||||
running so that workflow tasks are processed by Qinling. |
||||
|
||||
Running Multiple Qinling 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:: |
||||
|
||||
$ qinling-server --server api,engine --config-file <path-to-qinling.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 |
||||
Qinling servers are launched on the same process. Otherwise, messages do not |
||||
get delivered if the Qinling servers are launched on different processes |
||||
because the "fake" transport is using an in process queue. |
||||
|
||||
Qinling Client Installation |
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
||||
|
||||
Please refer to :doc:`Qinling Client / CLI Guide </guides/mistralclient_guide>` |
||||
Loading…
Reference in new issue