diff --git a/README.rst b/README.rst index 905a7bae..7c9295d0 100644 --- a/README.rst +++ b/README.rst @@ -17,7 +17,7 @@ documentation `_ for an +Please see `install.rst `_ for an installation guide. diff --git a/doc/source/install.rst b/doc/source/install.rst index 79ea0ce6..e5414fee 100644 --- a/doc/source/install.rst +++ b/doc/source/install.rst @@ -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 ` + + 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 `_ requires that you use a version <1.70 or >= 1.7.2. -Now create your virtualenv:: +Now create your virtualenv. + +.. code-block:: bash $ cd /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 +`_ 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= 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 + `_ 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 -` 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 . + +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 `_ + + Contributing ------------ -For additional developer information, take a look at `CONTRIBUTING.rst -`_ and the `developer documentation `_. +For additional developer information, take a look at +:doc:`the contributing guide `.