Added developer documentation

* Updated README file
* Updated contrib/devstack/README
* Added documentation for Devstack installation
* Added documentation for manual installation of the API and Engine services
* Added basic contributing guide
* Added extended contributing guide
* Added HACKING.rst to the root of the project
* Added development guidelines
* Sets simple Sphinx theme

Partially implements blueprint: murano-dev-doc-05

Change-Id: Ib7d7b416ccc61667ed96297555db2ef5dca9ae67
This commit is contained in:
Ruslan Kamaldinov 2014-04-17 03:49:09 +04:00
parent 51ddaac328
commit 3b1cec10be
15 changed files with 403 additions and 148 deletions

45
CONTRIBUTING.rst Normal file
View File

@ -0,0 +1,45 @@
======================
Contributing to Murano
======================
If you're interested in contributing to the Murano project,
the following will help get you started.
Contributor License Agreement
=============================
In order to contribute to the Murano project, you need to have
signed OpenStack's contributor's agreement:
* http://wiki.openstack.org/HowToContribute
* http://wiki.openstack.org/CLA
Project Hosting Details
=======================
* Bug tracker
https://launchpad.net/murano
* Mailing list (prefix subjects with ``[Murano]`` for faster responses)
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
* Wiki
https://wiki.openstack.org/wiki/Murano
* IRC channel
* #murano at FreeNode
* https://wiki.openstack.org/wiki/Meetings#Murano_meeting
* Code Hosting
* https://git.openstack.org/cgit/stackforge/murano-api
* https://git.openstack.org/cgit/stackforge/murano-agent
* https://git.openstack.org/cgit/stackforge/murano-dashboard
* Code Review
* https://review.openstack.org/#/q/murano+AND+status:+open,n,z
* https://wiki.openstack.org/wiki/GerritWorkflow

4
HACKING.rst Normal file
View File

@ -0,0 +1,4 @@
Style Commandments
==================
Read the OpenStack Style Commandments http://docs.openstack.org/developer/hacking/

View File

@ -5,35 +5,25 @@ developers and cloud administrators to publish various cloud-ready
applications in a browsable categorised catalog, which may be used by the
cloud users (including the inexperienced ones) to pick-up the needed
applications and services and composes the reliable environments out of them
in a “push-the-button” manner.
in a "push-the-button" manner.
murano-api
----------
murano-api is a project that serves as service endpoint for communication
with a client. It exposes API via HTTP protocol to manipulate with different
object model entities representing environment and environment components
like applications.
Project Resources
-----------------
* `Murano at Launchpad <http://launchpad.net/murano>`__
* `Wiki <https://wiki.openstack.org/wiki/Murano>`__
* `Code Review <https://review.openstack.org/>`__
* `Sources <https://wiki.openstack.org/wiki/Murano/SourceCode>`__
* `Developers Guide <http://murano-docs.github.io/latest/developers-guide/content/ch02.html>`__
How To Participate
------------------
If you would like to ask some questions or make proposals, feel free to reach
us on #murano IRC channel at FreeNode. Typically somebody from our team will
be online at IRC from 6:00 to 20:00 UTC. You can also contact Murano community
directly by openstack-dev@lists.openstack.org adding [Murano] to a subject.
Project status, bugs, and blueprints are tracked on Launchpad:
Were holding public weekly meetings on Tuesdays at 17:00 UTC
on #openstack-meeting-alt IRC channel at FreeNode.
https://launchpad.net/murano
If you want to contribute either to docs or to code, simply send us change
request via `gerrit <https://review.openstack.org/>`__.
You can `file bugs <https://bugs.launchpad.net/murano/+filebug>`__ and
`register blueprints <https://blueprints.launchpad.net/murano/+addspec>`__ on
Launchpad.
Developer documentation can be found here:
https://murano-api.readthedocs.org
Additional resources are linked from the project wiki page:
https://wiki.openstack.org/wiki/Murano
License
-------
Apache License Version 2.0 http://www.apache.org/licenses/LICENSE-2.0

View File

@ -1,18 +0,0 @@
The contrib/devstack/ directory contains the files necessary to integrate Murano with Devstack.
To install:
$ DEVSTACK_DIR=.../path/to/devstack
$ cp lib/murano ${DEVSTACK_DIR}/lib
$ cp lib/murano-dashboard ${DEVSTACK_DIR}/lib
$ cp extras.d/70-murano.sh ${DEVSTACK_DIR}/extras.d
To configure Devstack to run Murano:
$ cd ${DEVSTACK_DIR}
$ echo "enable_service murano" >> localrc
$ echo "enable_service murano-api" >> localrc
Run devstack as normal:
$ ./stack.sh

View File

@ -0,0 +1,24 @@
1. Follow Devstack documentation to setup a host for Devstack. Then clone
Devstack source code.
2. Copy Murano integration scripts to Devstack::
$ cp lib/murano ${DEVSTACK_DIR}/lib
$ cp lib/murano-dashboard ${DEVSTACK_DIR}/lib
$ cp extras.d/70-murano.sh ${DEVSTACK_DIR}/extras.d
3. Create a ``localrc`` file as input to devstack.
4. The Murano services are not enabled by default, so they must be
enabled in ``localrc`` before running ``stack.sh``. This example ``localrc``
file shows all of the settings required for Murano::
# Enable Heat
enable_service heat h-api h-api-cfn h-api-cw h-eng
# Enable Murano
enable_service murano murano-api murano-engine
5. Deploy your OpenStack Cloud with Murano::
$ ./stack.sh

View File

@ -0,0 +1,11 @@
<h3>Useful Links</h3>
<ul>
<li><a href="https://launchpad.net/murano">Murano @ Launchpad</a></li>
<li><a href="https://wiki.openstack.org/wiki/Murano">Murano @ OpenStack Wiki</a></li>
</ul>
{% if READTHEDOCS %}
<script type='text/javascript'>
$('div.body').css('margin', 0)
</script>
{% endif %}

View File

@ -0,0 +1,4 @@
{% extends "basic/layout.html" %}
{% set css_files = css_files + ['_static/tweaks.css'] %}
{% block relbar1 %}{% endblock relbar1 %}

View File

@ -0,0 +1,4 @@
[theme]
inherit = nature
stylesheet = nature.css
pygments_style = tango

View File

@ -36,13 +36,12 @@ from muranoapi import __version_info as version
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
'sphinx.ext.intersphinx',
]
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
'sphinx.ext.coverage', 'sphinx.ext.pngmath',
'sphinx.ext.viewcode']
intersphinx_mapping = {
'sphinx': ('http://sphinx.pocoo.org', None)
}
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
@ -74,7 +73,15 @@ show_authors = False
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
html_theme_path = ['.']
html_theme = '_theme'
# Custom sidebar templates, maps document names to template names.
html_sidebars = {
'index': ['sidebarlinks.html', 'localtoc.html', 'searchbox.html', 'sourcelink.html'],
'**': ['localtoc.html', 'relations.html',
'searchbox.html', 'sourcelink.html']
}
# -- Options for man page output --------------------------------------------

View File

@ -0,0 +1 @@
.. include:: ../../CONTRIBUTING.rst

81
doc/source/guidelines.rst Normal file
View File

@ -0,0 +1,81 @@
======================
Development Guidelines
======================
Coding Guidelines
-----------------
For all the code in Murano we have a rule - it should pass `PEP 8`_.
To check your code against PEP 8 run:
::
$ tox -e pep8
.. seealso::
* https://pep8.readthedocs.org/en/latest/
* https://flake8.readthedocs.org
* http://docs.openstack.org/developer/hacking/
Testing Guidelines
------------------
Murano has a suite of tests that are run on all submitted code,
and it is recommended that developers execute the tests themselves to
catch regressions early. Developers are also expected to keep the
test suite up-to-date with any submitted code changes.
Unit tests are located at ``muranoapi/tests``.
Murano's suite of unit tests can be executed in an isolated environment
with `Tox`_. To execute the unit tests run the following from the root of
Murano repo on Python 2.7:
::
$ tox -e py27
For Python 2.6:
::
$ tox -e py26
Documentation Guidelines
------------------------
Murano dev-docs are written using Sphinx / RST and located in the main repo
in ``doc`` directory.
The documentation in docstrings should follow the `PEP 257`_ conventions
(as mentioned in the `PEP 8`_ guidelines).
More specifically:
1. Triple quotes should be used for all docstrings.
2. If the docstring is simple and fits on one line, then just use
one line.
3. For docstrings that take multiple lines, there should be a newline
after the opening quotes, and before the closing quotes.
4. `Sphinx`_ is used to build documentation, so use the restructured text
markup to designate parameters, return values, etc. Documentation on
the sphinx specific markup can be found here:
Run the following command to build docs locally.
::
$ tox -e docs
.. _PEP 8: http://www.python.org/dev/peps/pep-0008/
.. _PEP 257: http://www.python.org/dev/peps/pep-0257/
.. _Tox: http://tox.testrun.org/
.. _Sphinx: http://sphinx.pocoo.org/markup/index.html

View File

@ -1,11 +1,11 @@
..
Copyright (c) 2013 Mirantis, Inc.
Copyright 2014 Mirantis, Inc.
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
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
@ -13,112 +13,55 @@
License for the specific language governing permissions and limitations
under the License.
==============================================
Welcome to Murano API Service!
==============================================
Murano API is a project that provides access to engine via API.
This document describes Murano API for contributors of the project,
and assumes that you are already familiar with Murano API from an
`end-user perspective`_.
.. _`end-user perspective`: http://murano.mirantis.com/
This documentation is generated by the Sphinx toolkit and lives in the source
tree.
Installation Guide
==================
Install
-------
1. Check out sources to some directory (<home>/murano)::
Welcome to Murano!
==================
user@work:~/$ git clone https://github.com/Mirantis/murano-api.git
Introduction
============
2. Install Murano API::
Murano Project introduces an application catalog, which allows application
developers and cloud administrators to publish various cloud-ready applications
in a browsable categorised catalog. It may be used by the cloud users
(including the unexperienced ones) to pick-up the needed applications and
services and composes the reliable environments out of them in a
"push-the-button" manner.
user@work:~/$ cd murano/api && sudo python setup.py install
Key goal is to provide UI and API which allows to compose and deploy composite
environments on the Application abstraction level and then manage their
lifecycle.
Configure
---------
1. Open first configuration file for editing::
user@work:~/$ cd murano/api/etc && nano murano-api.conf
2. Configure according to you environment (please note rabbitmq section)::
[DEFAULT]
# Show more verbose log output (sets INFO log level output)
verbose = True
# Show debugging output in logs (sets DEBUG log level output)
debug = True
# Address to bind the server to
bind_host = 0.0.0.0
# Port the bind the server to
bind_port = 8082
# Log to this file. Make sure the user running skeleton-api has
# permissions to write to this file!
log_file = /tmp/murano-api.log
#A valid SQLAlchemy connection string for the metadata database
sql_connection = sqlite:///murano.sqlite
[reports]
results_exchange = task-results
results_queue = task-results
reports_exchange = task-reports
reports_queue = task-reports
[rabbitmq]
host = localhost
port = 5672
# RabbitMQ credentials. Fresh RabbitMQ installation has "guest" account with "guest" password.
# It is recommended to create dedicated user account for Murano using RabbitMQ web console or command line utility
login = guest
password = guest
# RabbitMQ virtual host (vhost). Fresh RabbitMQ installation has "/" vhost preconfigured.
# It is recommended to create dedicated vhost for Murano using RabbitMQ web console or command line utility
virtual_host = /
ssl = False
ca_certs =
Murano consists of three source code repositories:
* `murano-api`_ - is the main repository. It contains code for Murano API
server, Murano engine and MuranoPL
* `murano-agent`_ - agent which runs on guest VMs and executes deployment
plan
* `murano-dashboard`_ - Murano UI implemented as a plugin for OpenStack
Dashboard
3. Open second configuration file for editing::
.. _murano-api: https://git.openstack.org/cgit/stackforge/murano-api/
.. _murano-agent: https://git.openstack.org/cgit/stackforge/murano-agent/
.. _murano-dashboard: https://git.openstack.org/cgit/stackforge/murano-dashboard/
smelikyan@work:~/cd murano/api/etc && nano murano-api.conf
4. Configure according to you environment (please note filter:authtoken section)::
This documentation offers information on how Murano works and how to
contribute to the project.
[pipeline:murano-api]
pipeline = authtoken context apiv1app
[app:apiv1app]
paste.app_factory = muranoapi.api.v1.router:API.factory
[filter:context]
paste.filter_factory = muranoapi.api.middleware.context:ContextMiddleware.factory
[filter:authtoken]
paste.filter_factory = keystoneclient.middleware.auth_token:filter_factory
auth_host = localhost
auth_port = 35357
auth_protocol = http
admin_tenant_name = admin
admin_user = admin
admin_password = password
signing_dir = /tmp/keystone-signing-muranoapi
Run
----
Run Murano API and supply valid configuration file::
user@work:~/$ murano-api --config-file=./murano/api/etc/murano-api.conf
Man Pages
=========
Table of contents
=================
.. toctree::
:maxdepth: 1
:maxdepth: 2
man/muranoapi
contributing
guidelines
install/index
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

View File

@ -0,0 +1,29 @@
..
Copyright 2014 2014 Mirantis, Inc.
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.
================================================
Installing and Running the Development Version
================================================
The `contrib/devstack`_ directory contains the files necessary to integrate
Murano with `Devstack`_.
.. include:: ../../../contrib/devstack/README.rst
.. _Devstack: http://www.devstack.org/
.. _contrib/devstack: https://git.openstack.org/cgit/stackforge/murano-api/tree/contrib/devstack

View File

@ -0,0 +1,26 @@
..
Copyright 2014 Mirantis, Inc.
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.
.. _install:
==================
Installing Murano
==================
.. toctree::
:maxdepth: 2
development
manual

View File

@ -0,0 +1,104 @@
..
Copyright 2014 Mirantis, Inc.
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.
.. _installing_manually:
================================
Installing and Running Manually
================================
Installing prerequisites
========================
First you need to install a number of packages with your OS package manager.
The list of packages depends on the OS you use.
* For Ubuntu run:
::
$ sudo apt-get install python-setuptools python-dev
* For Fedora:
::
$ sudo yum install gcc python-setuptools python-devel
.. note::
Fedora support wasn't thoroughly tested. We do not guarantee that Murano
will work on Fedora.
* For CentOS:
::
$ sudo yum install gcc python-setuptools python-devel
$ sudo easy_install pip
Installing the API service and Engine
=====================================
1. Clone the Murano git repository to the management server:
::
$ cd /opt/stack
$ git clone https://git.openstack.org/stackforge/murano-api.git
2. Configure the database. Murano can run with MySQL and SQLite. MySQL is
required for produciton installation, SQLite can be used for developemnt
purposes only. Let's setup MySQL database for Murano:
::
$ apt-get install python-mysqldb mysql-server
$ mysql -u root -p
mysql> CREATE DATABASE murano;
mysql> GRANT ALL PRIVILEGES ON murano.* TO 'murano'@'localhost' \
IDENTIFIED BY 'MURANO_DBPASS';
mysql> exit;
3. Copy the sample configuration from the source tree to their final location:
::
$ mkdir -p /etc/murano
$ cp etc/murano/murano-api.conf.sample /etc/murano/murano-api.conf
$ cp etc/murano/murano-api-paste.ini /etc/murano/
4. Edit ``/etc/murano/murano-api.conf``
TODO(ruhe): document configuration options
5. Create database tables for Murano:
::
$ tox -e venv -- murano-manage --config-file /etc/murano/murano-api.conf db-sync
6. Launch Murano API service:
::
$ tox -e venv -- murano-api --config-file /etc/murano/murano-api.conf
7. Launch Murano Engine service:
::
$ tox -e venv -- murano-engine --config-file /etc/murano/murano-api.conf