Update Tuskar Install Documentation
Change-Id: Ic271db6b05c4537d2c8eaaac879c1d3ec197e905
This commit is contained in:
Dougal Matthews
Alexis Lee
parent
72b312c82d
commit
1b879aacfd
@ -17,7 +17,7 @@ documentation <http://git.openstack.org/cgit/openstack/tuskar/tree/docs/index.rs
|
||||
Installation Information
|
||||
------------------------
|
||||
|
||||
Please see `INSTALL.rst <doc/source/install.rst>`_ for an
|
||||
Please see `install.rst <doc/source/install.rst>`_ for an
|
||||
installation guide.
|
||||
|
||||
|
||||
|
||||
@ -1,8 +1,10 @@
|
||||
==================
|
||||
Installation Guide
|
||||
==================
|
||||
============================
|
||||
Developer Installation Guide
|
||||
============================
|
||||
|
||||
The Tuskar source code should be pulled directly from git::
|
||||
The Tuskar source code should be pulled directly from git.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git clone https://git.openstack.org/openstack/tuskar
|
||||
|
||||
@ -10,104 +12,184 @@ The Tuskar source code should be pulled directly from git::
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
Setting up a local environment for development can be done with tox::
|
||||
Setting up a local environment for development can be done with
|
||||
tox.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# install prerequisites
|
||||
* Ubuntu/Debian:
|
||||
$ sudo apt-get install python-dev swig libssl-dev python-pip libmysqlclient-dev libxml2-dev libxslt-dev gcc
|
||||
* Fedora/RHEL:
|
||||
$ sudo yum install python-devel swig openssl-devel python-pip mysql-devel libxml2-devel libxslt-devel gcc
|
||||
# Note that as of Fedora 19, you need to use the community
|
||||
upstream for mysql, called mariadb-devel
|
||||
$ sudo yum install python-devel python-pip libxml2-devel \
|
||||
libxslt-devel postgresql-devel mariadb-devel
|
||||
|
||||
$ sudo pip install virtualenv setuptools-git flake8 tox
|
||||
* Ubuntu/Debian:
|
||||
$ sudo apt-get install python-dev python-pip libxml2-dev \
|
||||
libxslt-dev libpq-dev libmysqlclient-dev
|
||||
|
||||
.. note::
|
||||
An `issue with tox <https://bugs.launchpad.net/openstack-ci/+bug/1274135>`
|
||||
|
||||
If you wish you run Tuskar against MySQL or PostgreSQL you
|
||||
will need also install and configure these at this point.
|
||||
Otherwise you can run Tuskar with an sqlite database.
|
||||
|
||||
To run the Tuskar test suite you will also need to install Tox.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ sudo pip install tox
|
||||
|
||||
.. note::
|
||||
An `issue with tox <https://bugs.launchpad.net/openstack-ci/+bug/1274135>`_
|
||||
requires that you use a version <1.70 or >= 1.7.2.
|
||||
|
||||
Now create your virtualenv::
|
||||
Now create your virtualenv.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ cd <your_src_dir>/tuskar
|
||||
$ tox -e py27
|
||||
$ tox -e venv
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
If ``pip install`` fails due to an outdated setuptools, you can try to
|
||||
update it first::
|
||||
If ``pip install`` fails due to an outdated setuptools, you
|
||||
can try to update it first.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ sudo pip install --upgrade setuptools
|
||||
|
||||
To run the test suite use the following command. This will run
|
||||
against Python 2.6, Python 2.7 and run the `flake8
|
||||
<https://flake8.readthedocs.org>`_ code linting.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ tox
|
||||
|
||||
.. note::
|
||||
|
||||
If you only have access to Python 2.6 or 2.7 locally pass
|
||||
in `-e py26` or `-e py27` respectively.
|
||||
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
Copy the sample configuration file:
|
||||
|
||||
::
|
||||
.. code-block:: bash
|
||||
|
||||
$ cp etc/tuskar/tuskar.conf.sample etc/tuskar/tuskar.conf
|
||||
|
||||
We need to tell tuskar where to connect to database. Edit the config file in
|
||||
``database`` section and change
|
||||
We need to tell tuskar where to connect to database. Edit the
|
||||
config file in ``database`` section and change
|
||||
|
||||
::
|
||||
.. code-block:: ini
|
||||
|
||||
#connection=<None>
|
||||
|
||||
to
|
||||
|
||||
::
|
||||
.. code-block:: ini
|
||||
|
||||
connection=sqlite:///tuskar/tuskar.sqlite
|
||||
|
||||
We need to initialise the database schema::
|
||||
.. note::
|
||||
|
||||
If you are using a different database backend, you will need
|
||||
to enter a `SQLAlchemy compatible conection string
|
||||
<http://docs.sqlalchemy.org/en/latest/core/engines.html
|
||||
#database-urls>`_ for this setting.
|
||||
|
||||
We need to initialise the database schema.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# activate the virtualenv
|
||||
$ source .tox/py27/bin/activate
|
||||
$ source .tox/venv/bin/activate
|
||||
|
||||
# if you delete tuskar.sqlite this will force creation of tables again - e.g.
|
||||
# if you added a new resource table definitions etc in an existing migration
|
||||
# file
|
||||
$ tuskar-dbsync --config-file etc/tuskar/tuskar.conf
|
||||
|
||||
You can verify this was successful (in addition to seeing no error output)
|
||||
with::
|
||||
You can verify this was successful (in addition to seeing no
|
||||
error output) with.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ sqlite3 tuskar/tuskar.sqlite .schema
|
||||
|
||||
Then, launch the app::
|
||||
Then, launch the app.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ tuskar-api --config-file etc/tuskar/tuskar.conf
|
||||
|
||||
You can then verify that everything worked by running.::
|
||||
You can then verify that everything worked by running.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ curl -v -X GET -H 'Accept: application/json' http://0.0.0.0:8585/v2/plans/ | python -mjson.tool
|
||||
|
||||
This command should return JSON with an empty result set.
|
||||
|
||||
Keystone Configuration
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
By default, Tuskar is configured to skip authentication for REST API calls.
|
||||
Keystone authentication can be enabled by making the appropriate changes to the
|
||||
``tuskar.conf`` file as described in the `keystone documentation
|
||||
<http://docs.openstack.org/developer/keystone/configuringservices.html>`
|
||||
|
||||
Running Tuskar API
|
||||
------------------
|
||||
|
||||
Whenever you want to run the API again, just switch to the virtualenv and run
|
||||
`tuskar-api` command:
|
||||
Whenever you want to run the API again, just switch to the
|
||||
virtualenv and run `tuskar-api` command.
|
||||
|
||||
::
|
||||
.. code-block:: bash
|
||||
|
||||
$ source .tox/py27/bin/activate
|
||||
$ source .tox/venv/bin/activate
|
||||
$ tuskar-api --config-file etc/tuskar/tuskar.conf
|
||||
|
||||
|
||||
Loading Initial Roles
|
||||
---------------------
|
||||
|
||||
Tuskar needs to be provided with a set of roles that can be added
|
||||
to a deployment plan. The following steps will add the roles from
|
||||
the TripleO Heat Templates repository.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ git clone http://git.openstack.org/cgit/openstack/tripleo-heat-templates/
|
||||
$ cd tripleo-heat-templates
|
||||
$ tuskar-load-roles --config-file etc/tuskar/tuskar.conf \
|
||||
-r compute.yaml \
|
||||
-r controller.yaml
|
||||
|
||||
.. note::
|
||||
|
||||
Tuskar currently requires the TripleO Heat Template changes
|
||||
in review 123100 <https://review.openstack.org/#/c/123100/>.
|
||||
|
||||
After this, if the Tuskar API isn't running, start it with the
|
||||
above command and the following curl command should show you the
|
||||
loaded roles.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ curl -v -X GET -H 'Accept: application/json' http://0.0.0.0:8585/v2/roles/ | python -mjson.tool
|
||||
|
||||
|
||||
|
||||
Keystone Configuration
|
||||
----------------------
|
||||
|
||||
By default, Tuskar is configured to skip authentication for REST
|
||||
API calls. Keystone authentication can be enabled by making the
|
||||
appropriate changes to the ``tuskar.conf`` file as described in
|
||||
the `keystone documentation <http://docs.openstack.org/developer/
|
||||
keystone/configuringservices.html>`_
|
||||
|
||||
|
||||
Contributing
|
||||
------------
|
||||
|
||||
For additional developer information, take a look at `CONTRIBUTING.rst
|
||||
<docs/CONTRIBUTING.rst>`_ and the `developer documentation <docs/index.rst>`_.
|
||||
For additional developer information, take a look at
|
||||
:doc:`the contributing guide <contributing>`.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user