Merge "Update installation documentation"

This commit is contained in:
Jenkins 2015-08-19 10:14:42 +00:00 committed by Gerrit Code Review
commit bc427fb976
5 changed files with 126 additions and 80 deletions

View File

@ -40,11 +40,10 @@ after their software has been incorporated into the distro or cloud.
vendors. It can be used by vendors in house to compare interoperability vendors. It can be used by vendors in house to compare interoperability
data over time. data over time.
* API server install docs: `doc/refstack.md <doc/refstack.md>`_ * API and UI install docs: `doc/refstack.md <doc/refstack.md>`_
* UI server install docs: `refstack-ui/README.rst <refstack-ui/README.rst>`_
* repository: http://git.openstack.org/cgit/stackforge/refstack * repository: http://git.openstack.org/cgit/stackforge/refstack
* storyboard: https://storyboard.openstack.org/#!/project/700 * storyboard: https://storyboard.openstack.org/#!/project/700
* reviews: https://review.OpenStack.org/#q,status:open+refstack,n,z * reviews: https://review.openstack.org/#q,status:open+refstack,n,z
* **refstack-client** * **refstack-client**
refstack-client contains the tools you will need to run the DefCore tests. refstack-client contains the tools you will need to run the DefCore tests.

View File

@ -1,6 +1,6 @@
Refstack Quickstart Refstack Quickstart
=================== ===================
####Install dependencies (on ubuntu 14.x).. ####Install API dependencies (on ubuntu 14.x)..
- `sudo apt-get install git python-dev libssl-dev python-setuptools` - `sudo apt-get install git python-dev libssl-dev python-setuptools`
@ -10,7 +10,13 @@ Refstack Quickstart
- `sudo easy_install -U virtualenv` - `sudo easy_install -U virtualenv`
####Setup the refstack database ####Install Refstack UI dependencies
- `curl -sL https://deb.nodesource.com/setup | sudo bash -`
- `sudo apt-get install nodejs`
####Setup the Refstack database
- Log into MySQL: `mysql -u root -p` - Log into MySQL: `mysql -u root -p`
@ -43,23 +49,27 @@ Refstack Quickstart
- `cd refstack` - `cd refstack`
- Creare virtual environment: `virtualenv .venv --system-site-package` - Create virtual environment: `virtualenv .venv --system-site-package`
- Source to virtual environment: `source .venv/bin/activate` - Source to virtual environment: `source .venv/bin/activate`
####Install Refstack application (on ubuntu 14.x).. ####Install Refstack application (on ubuntu 14.x)..
- `pip install .` - `pip install .`
####Configuration file preparation ####Install needed Refstack UI library dependencies
- `npm install`
####API configuration file preparation
- Make a copy of the sample config file (etc/refstack.conf.sample) and - Make a copy of the sample config file (etc/refstack.conf.sample) and
update it with the correct information of your environment. Examples update it with the correct information of your environment. Examples
of the config parameters with default values are included in the of the config parameters with default values are included in the
sample config file. sample config file.
- At the minimum, the following values should be updated: - You should ensure that the following values in the config file are noted and
properly set:
- `connection` field in the `[database]`section. - `connection` field in the `[database]`section.
@ -67,11 +77,77 @@ Refstack Quickstart
`#connection = <None>` to `#connection = <None>` to
`connection = mysql+pymysql://refstack:<your password>@x.x.x.x/refstack` `connection = mysql+pymysql://refstack:<your password>@x.x.x.x/refstack`
- `allowed_cors_origins`. - `ui_url` field in the `[DEFAULT]` section.
Update to your UI server address. For example: This should be the URL that the UI can be accessed from. This will likely
`allowed_cors_origins = http://192.168.56.104:8080` be in the form `http://<your server IP>:8000` (8000 being the default port
Refstack is hosted on). For example: `http://192.168.56.101:8000`
- `api_url` field in the `[api]` section.
This should be the URL that the API can be accessed from. This, in most
cases, will be the same as the value for `ui_url` above.
- `app_dev_mode` field in the `[api]` section.
Set this field to true if you aren't creating a production-level Refstack
deployment and are just trying things out or developing. Setting this field
to true will allow you to quickly bring up both the API and UI together,
with the UI files being served by a simple file server that comes with
Pecan.
####Create UI config file
From the Refstack project root directory, create a config.json file
and specify your API endpoint inside this file. This will be something like
{"refstackApiUrl": "http://192.168.56.101:8000/v1"}:
- `cp refstack-ui/app/config.json.sample refstack-ui/app/config.json`
####Openstack OpenID endpoint configuration (optional)
If you are only interested in the uploading and viewing of result sets, then
this section can be ignored. However, in order for user accounts and
authentication to work, you need to make sure you are properly configured
with an OpenStack OpenID endpoint. There are two options:
* Use the official endpoint [openstackid.org](https://openstackid.org)
* Host your own openstackid endpoint
Since openstackid checks for valid top-level domains, in both options you will
likely have to edit the hosts file of the system where your web-browser for
viewing the Refstack site resides. On Linux systems, you would modify
`/etc/hosts`, adding a line like the following:
`<Refstack server IP> <some valid domain name>`
Example:
`192.168.56.101 myrefstack.com`
On Windows, you would do the same in `%SystemRoot%\System32\drivers\etc\hosts`.
Alternatively, you can add a custom DNS record with the domain name mapping
if possible.
Note that doing this requires you to modify the config.json file and the
`api_url` and `ui_url` fields in refstack.conf to use this domain name instead
of the IP.
**Option 1 - Use Official Endpoint**
Using the official site is probably the easiest option as no additional
configuration is needed besides the hosts file modifications as noted above.
Refstack, by default, points to this endpoint.
**Option 2 - Use Local Endpoint**
Instructions for setting this up are outside of the scope of this doc, but you
can get started at [https://github.com/openstack-infra/openstackid]
(https://github.com/openstack-infra/openstackid)
or [https://github.com/fremontlabs/vagrant-openstackid]
(https://github.com/fremontlabs/vagrant-openstackid).
You would then need to modify the `openstack_openid_endpoint` field in the
`[osid]` section in refstack.conf to match the local endpoint.
####Database sync ####Database sync
@ -79,7 +155,9 @@ Refstack Quickstart
`refstack-manage --config-file /path/to/refstack.conf version` `refstack-manage --config-file /path/to/refstack.conf version`
The response will show the current database revision. If the revision is `None` (indicating a clear database), the following command should be performed to upgrade the database to the latest revision: The response will show the current database revision. If the revision is
`None` (indicating a clear database), the following command should be
performed to upgrade the database to the latest revision:
- Upgrade database to latest revision: - Upgrade database to latest revision:
@ -94,13 +172,23 @@ Refstack Quickstart
####Start Refstack ####Start Refstack
For the most basic setup that you can try right now, just kick off A simple way to start refstack is to just kick off gunicorn using the
gunicorn: `refstack-api` executable:
- `refstack-api --env REFSTACK_OSLO_CONFIG=/path/to/refstack.conf` - `refstack-api --env REFSTACK_OSLO_CONFIG=/path/to/refstack.conf`
If `app_dev_mode` is set to true, this will launch both the UI and API.
Now available: Now available:
- `http://localhost:8000/v1/results` with response JSON including records consisted of `<test run id>`, `<upload date>` and `<cloud cpid>` of the test runs. The default response is limited to one page of the most recent uploaded test run records. The number of records per page is configurable via the Refstack configuration file. Filtering parameters such as page, start_date, end_date ... can also be used to specify the desired records. For example: get `http://localhost:8000/v1/results?page=n` will return page n of the data. - `http://<your server IP>:8000/v1/results` with response JSON including
records consisting of `<test run id>` and `<upload date>` of the test runs.
The default response is limited to one page of the most recent uploaded test
run records. The number of records per page is configurable via the Refstack
configuration file. Filtering parameters such as page, start_date, and
end_date can also be used to specify the desired records. For example:
GET `http://<your server IP>:8000/v1/results?page=n` will return page *n*
of the data.
- `http://localhost:8000/v1/results/<test run id>` with response JSON including the detail test results of the specified `<test run id>` - `http://<your server IP>:8000/v1/results/<test run id>` with response JSON
including the detail test results of the specified `<test run id>`

View File

@ -114,19 +114,17 @@
# The directory where your static files can be found. Pecan comes with # The directory where your static files can be found. Pecan comes with
# middleware that can be used to serve static files (like CSS and # middleware that can be used to serve static files (like CSS and
# Javascript files) during development. %(project_root)s is special # Javascript files) during development. Here, a special variable
# variable that point to the root directory of Refstack project. Value # %(project_root)s can be used to point to the root directory of Refstack
# of this option must contain %(project_root)s variable. Directory # project's main module, so paths can be specified relative to that.
# with static files specified relative the project root. (string # (string value)
# value) #static_root = refstack-ui/app
#static_root = %(project_root)s/static
# Points to the directory where your template files live. # Points to the directory where your template files live. Here, a special
# %(project_root)s is special variable that point to the root # variable %(project_root)s can be used to point to the root directory of
# directory of Refstack project. Value of this option must contain # the Refstack project's main module, so paths can be specified relative to
# %(project_root)s variable. Directory with template files specified # that. (string value)
# relative the project root. (string value) #template_path = refstack-ui/app
#template_path = %(project_root)s/templates
# List of sites allowed cross-site resource access. If this is empty, # List of sites allowed cross-site resource access. If this is empty,
# only same-origin requests are allowed. (list value) # only same-origin requests are allowed. (list value)

View File

@ -1,37 +0,0 @@
=======================
Refstack User Interface
=======================
User interface for interacting with the Refstack API.
Setup
=====
From the Refstack project root directory, create a config.json file
and specify your API endpoint inside this file:
:code:`cp refstack-ui/app/config.json.sample refstack-ui/app/config.json`
You can start a development server by doing the following:
Install NodeJS and NPM:
:code:`curl -sL https://deb.nodesource.com/setup | sudo bash -`
:code:`sudo apt-get install nodejs`
Install dependencies and start the server:
:code:`npm start`
Doing this will automatically perform :code:`npm start` and :code:`bower install`
to get all dependencies.
By default, as noted in package.json, the server will use 0.0.0.0:8080.
Test
====
To run unit tests, simply perform the following:
:code:`npm test`

View File

@ -47,23 +47,21 @@ API_OPTS = [
help='Url of public Refstack API.' help='Url of public Refstack API.'
), ),
cfg.StrOpt('static_root', cfg.StrOpt('static_root',
default='%(project_root)s/static', default='refstack-ui/app',
help='The directory where your static files can ' help='The directory where your static files can be found. '
'be found. Pecan comes with middleware that can be used ' 'Pecan comes with middleware that can be used to serve '
'to serve static files (like CSS and Javascript files) ' 'static files (like CSS and Javascript files) during '
'during development. %(project_root)s is special variable ' 'development. Here, a special variable %(project_root)s '
'that point to the root directory of Refstack project. ' 'can be used to point to the root directory of the '
'Value of this option must contain %(project_root)s ' 'Refstack project\'s module, so paths can be specified '
'variable. Directory with static files specified relative ' 'relative to that.'
'the project root.'
), ),
cfg.StrOpt('template_path', cfg.StrOpt('template_path',
default='%(project_root)s/templates', default='refstack-ui/app',
help='Points to the directory where your template files live. ' help='Points to the directory where your template files live. '
'%(project_root)s is special variable that point to the ' 'Here, a special variable %(project_root)s can be used to '
'root directory of Refstack project. Value of this option ' 'point to the root directory of the Refstack project\'s '
'must contain %(project_root)s variable. Directory with ' 'main module, so paths can be specified relative to that.'
'template files specified relative the project root.'
), ),
cfg.ListOpt('allowed_cors_origins', cfg.ListOpt('allowed_cors_origins',
default=[], default=[],