doc: add draft installation instructions

Add some initial documentation so that people can test the code.

Change-Id: I75157e95781c0b993c11683ba353155bc2384e1d

doc/source/index.rst

@@ -6,14 +6,18 @@
 Welcome to ooi's documentation!
 ========================================================
 
+ooi is an implementation the Open Grid Forum's `Open Cloud Computing Interface
+(OCCI)`_ for `OpenStack`_.
+
+.. _Open Cloud Computing Interface (OCCI): http://www.occi-wg.org
+.. _OpenStack: http://www.openstack.org
+
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
-   readme
    installation
-   usage
 
 Indices and tables
 ==================

doc/source/installation.rst

@@ -2,11 +2,52 @@
 Installation
 ============
 
-At the command line::
+Note that ooi is still under development, so documentation is a bit naive. In
+order to install and test ooi, perform the steps below.
 
-    $ pip install ooi
+Get the latest source code::
 
-Or, if you have virtualenvwrapper installed::
+    $ git clone https://github.com/stackforge/ooi.git
 
-    $ mkvirtualenv ooi
-    $ pip install ooi
+Install it::
+
+    $ cd ooi
+    $ pip install .
+
+Add it to your OpenStack installation. Edit your ``/etc/nova/api-paste.ini``.
+In the ``[composite:osapi_compute]`` add the following::
+
+    [composite:osapi_compute]
+    # (...)
+    /occi1.1: occi_11
+
+Afterwards, add the OCCI filter like this::
+
+    [filter:occi]
+    paste.filter_factory = ooi.wsgi:OCCIMiddleware.factory
+    openstack_version = /v2
+
+Substitute ``openstack_version`` with the API version that you are going to
+use, taken from the ``[composite:osapi_compute]`` section.  So far we have
+tested it with the ``v2`` version, so the correct value should be ``/v2``.
+
+The last step is to duplicate the ``composite`` section corresponding to the
+configured version, rename it to the configured value above (in this case
+we have used ``occi_11`` above), and adding the ``occi`` filter just before the
+``osapi_compute_app`` component of the pipeline. So, in this case where ``v2``
+has been configured, the ``[composite:openstack_compute_api_v2]`` should be
+duplicated as follows::
+
+    [composite:occi_11]
+    use = call:nova.api.auth:pipeline_factory
+    noauth = compute_req_id faultwrap sizelimit noauth ratelimit occi osapi_compute_app_v2
+    keystone = compute_req_id faultwrap sizelimit occi authtoken keystonecontext ratelimit occi osapi_compute_app_v2
+    keystone_nolimit = compute_req_id faultwrap sizelimit authtoken keystonecontext occi osapi_compute_app_v2
+
+If everything is OK, after rebooting the ``nova-api`` service you should be able
+to access your OCCI endpoint at::
+
+    $ nova credentials
+    # Grab the token
+    $ export KID=<token>
+    $ curl -H "x-auth-token: $KID" http://localhost:8774/occi1.1/-/

doc/source/readme.rst

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

doc/source/usage.rst

@@ -1,3 +0,0 @@
-========
-Usage
-========