openstack/rally
Code Issues Proposed changes

[docs][2] Re-design docs to cover all user-groups

Browse Source 
First pack of changes in upcoming chain to redesign Rally docs.
All information related to the installation and upgrades process
separated and refactored. Modified files fit 80 symbols margin
where possible.

[TODO] continue with other parts of the docs:
       - Quick start aka Rally step-by-step
       - Command Line Interface
       - Rally Task Component
       - Rally Verification Component
       - Rally Plugins, Rally Plugins Reference
       - Contribute to Rally
       - Request New Features
       - Project Info
[TODO] add 80 symbols margin check similar to what
       Performance Documentation has

Change-Id: I0075be010fcad98272cec0928bcd29ca7b655d33
This commit is contained in:
Dina Belova 2016-11-16 13:28:10 -08:00
parent 51cbe8df32
commit 4292063876
7 changed files with 76 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
devstack/README.rst
View File

@ -1,15 +1,30 @@
=============================== Rally with DevStack all-in-one installation
Installing Rally using devstack -------------------------------------------
===============================
This directory contains the files necessary to integrate Rally with devstack. It is also possible to install Rally with DevStack. First, clone the
corresponding repositories:
To configure devstack to run rally edit ``${DEVSTACK_DIR}/local.conf`` file and add:: .. code-block:: bash
git clone https://git.openstack.org/openstack-dev/devstack
git clone https://github.com/openstack/rally
Then, configure DevStack to run Rally. First, create your ``local.conf`` file:
.. code-block:: bash
cd devstack
cp samples/local.conf local.conf
Next, edit local.conf: add the following line to the ``[[local|localrc]]``
section.
.. code-block:: bash
enable_plugin rally https://github.com/openstack/rally master enable_plugin rally https://github.com/openstack/rally master
to the ``[[local|localrc]]`` section. Finally, run DevStack as usually:
Run devstack as normal:: .. code-block:: bash
$ ./stack.sh ./stack.sh

1
doc/source/db_migrations.rst
View File

@ -1 +0,0 @@
../../rally/common/db/sqlalchemy/migrations/README.rst

3
doc/source/index.rst
View File

@ -37,13 +37,12 @@ Contents
:maxdepth: 2 :maxdepth: 2
overview/index overview/index
install install_and_upgrade/index
tutorial tutorial
cli/cli_reference cli/cli_reference
reports reports
plugins plugins
plugin/plugin_reference plugin/plugin_reference
db_migrations
contribute contribute
gates gates
feature_requests feature_requests

1
doc/source/install_and_upgrade/db_migrations.rst Symbolic link
View File

@ -0,0 +1 @@
../../../rally/common/db/sqlalchemy/migrations/README.rst

24
doc/source/install_and_upgrade/index.rst Normal file
View File

@ -0,0 +1,24 @@
..
Copyright 2015 Mirantis Inc. 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.
=========================
Installation and upgrades
=========================
.. toctree::
:glob:
install
db_migrations

58
doc/source/install.rst → doc/source/install_and_upgrade/install.rst
View File

@ -15,14 +15,13 @@
.. _install: .. _install:
Installation Installation process
============ ====================
Automated installation Automated installation
---------------------- ----------------------
The easiest way to install Rally is by executing its `installation script The easiest way to install Rally is by executing its `installation script`_
<https://raw.githubusercontent.com/openstack/rally/master/install_rally.sh>`_
.. code-block:: bash .. code-block:: bash
@ -37,7 +36,7 @@ the required packages.
By default it will install Rally in a virtualenv in ``~/rally`` when By default it will install Rally in a virtualenv in ``~/rally`` when
run as standard user, or install system wide when run as root. You can run as standard user, or install system wide when run as root. You can
install Rally in a venv by using the option ``--target``: install Rally in a **venv** by using the option ``--target``:
.. code-block:: bash .. code-block:: bash
@ -90,50 +89,24 @@ is already installed in your system. If this is not the case, it will
exit, suggesting you the command to issue **as root** in order to exit, suggesting you the command to issue **as root** in order to
install the dependencies. install the dependencies.
You also have to set up the **Rally database** after the installation is complete: You also have to set up the **Rally database** after the installation is
complete:
.. code-block:: bash .. code-block:: bash
rally-manage db recreate rally-manage db recreate
.. include:: ../../../devstack/README.rst
Rally with DevStack all-in-one installation
-------------------------------------------
It is also possible to install Rally with DevStack. First, clone the corresponding repositories:
.. code-block:: bash
git clone https://git.openstack.org/openstack-dev/devstack
git clone https://github.com/openstack/rally
Then, configure DevStack to run Rally. First, create your ``local.conf`` file:
.. code-block:: bash
cd devstack
cp samples/local.conf local.conf
Next, edit local.conf:
add ``enable_plugin rally https://github.com/openstack/rally master`` to ``[[local|localrc]]`` section.
Finally, run DevStack as usually:
.. code-block:: bash
./stack.sh
Rally & Docker Rally & Docker
-------------- --------------
First you need to install Docker; Docker supplies `installation First you need to install Docker; Docker supplies `installation
instructions for various OSes instructions for various OSes`_.
<https://docs.docker.com/installation/>`_.
You can either use the official Rally Docker image, or build your own You can either use the official Rally Docker image, or build your own
from the Rally source. To do that, change directory to the root directory of the from the Rally source. To do that, change directory to the root directory of
Rally git repository and run: the Rally git repository and run:
.. code-block:: bash .. code-block:: bash
@ -145,7 +118,7 @@ If you build your own Docker image, substitute ``myrally`` for
The Rally Docker image is configured to store local settings and the The Rally Docker image is configured to store local settings and the
database in the user's home directory. For persistence of these data, database in the user's home directory. For persistence of these data,
you may want to keep this directory outside of the container. This may you may want to keep this directory outside of the container. This may
be done by the following steps: be done via the following steps:
.. code-block:: bash .. code-block:: bash
@ -162,7 +135,7 @@ be done by the following steps:
likely to work if your home directory has excessively open likely to work if your home directory has excessively open
permissions (e.g., ``0755``), which is not recommended. permissions (e.g., ``0755``), which is not recommended.
All task samples, docs and certification tasks you could find at /opt/rally/. You can find all task samples, docs and certification tasks at /opt/rally/.
Also you may want to save the last command as an alias: Also you may want to save the last command as an alias:
.. code-block:: bash .. code-block:: bash
@ -195,4 +168,9 @@ Rally currently has no SELinux policy, which is why it must be run in
Permissive mode for certain configurations. If you can help create an Permissive mode for certain configurations. If you can help create an
SELinux policy for Rally, please contribute! SELinux policy for Rally, please contribute!
More about docker: `https://www.docker.com/ <https://www.docker.com/>`_ More about docker: https://www.docker.com/
.. references:
.. _installation script: https://raw.githubusercontent.com/openstack/rally/master/install_rally.sh
.. _installation instructions for various OSes: https://docs.docker.com/installation/

15
rally/common/db/sqlalchemy/migrations/README.rst
View File

@ -15,8 +15,8 @@
.. _db_migrations: .. _db_migrations:
Database upgrade/downgrade in Rally Database upgrade in Rally
=================================== =========================
Information for users Information for users
--------------------- ---------------------
@ -55,8 +55,6 @@ DB migration in Rally is implemented via package *alembic*.
It is highly recommended to get familiar with it's documentation It is highly recommended to get familiar with it's documentation
available by the link_ before proceeding. available by the link_ before proceeding.
.. _link: https://alembic.readthedocs.org
If developer is about to change existing DB schema they should If developer is about to change existing DB schema they should
create new DB revision and migration script with the following command create new DB revision and migration script with the following command
@ -73,8 +71,9 @@ or
It will generate migration script -- a file named `<UUID>_<Message>.py` It will generate migration script -- a file named `<UUID>_<Message>.py`
located in `rally/common/db/sqlalchemy/migrations/versions`. located in `rally/common/db/sqlalchemy/migrations/versions`.
Alembic with parameter ``--autogenerate`` makes some "routine" job for developer, Alembic with parameter ``--autogenerate`` makes some "routine" job for
for example it makes some SQLite compatible batch expressions for migrations. developer, for example it makes some SQLite compatible batch expressions for
migrations.
Generated script should then be checked, edited if it is needed to be Generated script should then be checked, edited if it is needed to be
and added to Rally source tree. and added to Rally source tree.
@ -82,3 +81,7 @@ and added to Rally source tree.
**WARNING** Even though alembic supports schema downgrade, migration **WARNING** Even though alembic supports schema downgrade, migration
scripts provided along with Rally do not contain actual code for scripts provided along with Rally do not contain actual code for
downgrade. downgrade.
.. references:
.. _link: https://alembic.readthedocs.org