[WIP] - Documentation fix
Change-Id: I4ae3a0274b1f3201a44bbac516c00f16dec5ce55
This commit is contained in:
lpiwowar
parent
e4494b52fa
commit
50dea7ba3d
|
|
@ -30,6 +30,9 @@ import os
|
|||
# ones.
|
||||
extensions = ['openstackdocstheme']
|
||||
|
||||
# openstackdocstheme options
|
||||
openstackdocs_repo_name = 'osf/refstack'
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
#templates_path = ['_templates']
|
||||
|
||||
|
|
@ -103,7 +106,7 @@ pygments_style = 'sphinx'
|
|||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
html_theme = 'openstackdocs'
|
||||
html_theme = 'alabaster'
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
======================================
|
||||
How to upload test results to RefStack
|
||||
======================================
|
||||
|
||||
|
|
@ -7,38 +7,17 @@
|
|||
Welcome to RefStack's documentation!
|
||||
====================================
|
||||
|
||||
--------------
|
||||
About RefStack
|
||||
--------------
|
||||
.. include:: README.rst
|
||||
|
||||
|
||||
Content:
|
||||
--------
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:titlesonly:
|
||||
|
||||
README
|
||||
|
||||
--------------------------
|
||||
Installing RefStack Server
|
||||
--------------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
refstack
|
||||
run_in_docker
|
||||
|
||||
--------------
|
||||
Using RefStack
|
||||
--------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
uploading_private_results
|
||||
vendor_product
|
||||
test_result_management
|
||||
|
||||
------------------
|
||||
Indices and tables
|
||||
------------------
|
||||
|
||||
* :ref:`search`
|
||||
refstack_quickstart/index
|
||||
run_in_docker/index
|
||||
vendor_product_management/index
|
||||
how_to_upload_test_results/index
|
||||
test_result_management/index
|
||||
|
|
|
|||
|
|
@ -1,296 +0,0 @@
|
|||
RefStack Quickstart
|
||||
===================
|
||||
|
||||
You can use docker for `one-click setup <run_in_docker.html>`__ or follow
|
||||
step-by-step instructions below. These instructions have been tested on
|
||||
Ubuntu 14 and 16 LTS.
|
||||
|
||||
Install API dependencies
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
``sudo apt-get install git python-dev python-virtualenv libssl-dev build-essential libffi-dev``
|
||||
|
||||
``sudo apt-get install mysql-server python-mysqldb``
|
||||
|
||||
Install RefStack UI dependencies
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
``curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -``
|
||||
|
||||
``curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -``
|
||||
|
||||
``echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list``
|
||||
|
||||
``sudo apt-get update && sudo apt-get install -y nodejs yarn``
|
||||
|
||||
Setup the RefStack database
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
**Log into MySQL:**
|
||||
|
||||
``mysql -u root -p``
|
||||
|
||||
**After authentication, create the database:**
|
||||
|
||||
``CREATE DATABASE refstack;``
|
||||
|
||||
**Create a refstack user:**
|
||||
|
||||
``CREATE USER 'refstack'@'localhost' IDENTIFIED BY '<your password>';``
|
||||
|
||||
or using hash value for your password
|
||||
|
||||
``CREATE USER 'refstack'@'localhost' IDENTIFIED BY PASSWORD '<hash value of your password';``
|
||||
|
||||
**Grant privileges:**
|
||||
|
||||
``GRANT ALL PRIVILEGES ON refstack . * TO 'refstack'@'localhost';``
|
||||
|
||||
**Reload privileges:**
|
||||
|
||||
``FLUSH PRIVILEGES;``
|
||||
|
||||
**Exit MySQL:**
|
||||
|
||||
``quit``
|
||||
|
||||
Clone the repository
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
``git clone https://opendev.org/osf/refstack``
|
||||
|
||||
``cd refstack``
|
||||
|
||||
**Create virtual environment:**
|
||||
|
||||
``virtualenv .venv --system-site-package``
|
||||
|
||||
**Source to virtual environment:**
|
||||
|
||||
``source .venv/bin/activate``
|
||||
|
||||
**Update pip**
|
||||
|
||||
``pip install -U pip``
|
||||
|
||||
**Install environment pre-requirements**
|
||||
|
||||
# App server
|
||||
|
||||
``pip install gunicorn==18``
|
||||
|
||||
# python mysql connector
|
||||
|
||||
``pip install PyMySQL>=0.6.2,!=0.6.4``
|
||||
|
||||
Install RefStack application
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
``pip install .``
|
||||
|
||||
Install needed RefStack UI library dependencies
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
``yarn``
|
||||
|
||||
API configuration file preparation
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Make a copy of the sample config file (etc/refstack.conf.sample) and
|
||||
update it with the correct information of your environment. Examples
|
||||
of the config parameters with default values are included in the
|
||||
sample config file.
|
||||
|
||||
You should ensure that the following values in the config file are
|
||||
noted and properly set:
|
||||
|
||||
``connection`` field in the ``[database]``\ section.
|
||||
|
||||
For example, if the backend database is MySQL then update:
|
||||
|
||||
``#connection = <None>`` to
|
||||
``connection = mysql+pymysql://refstack:<your password>@x.x.x.x/refstack``
|
||||
|
||||
``ui_url`` field in the ``[DEFAULT]`` section.
|
||||
|
||||
This should be the URL that the UI can be accessed from. This will
|
||||
likely 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
|
||||
`Openstackid project <https://opendev.org/osf/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
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
**Check current revision:**
|
||||
|
||||
``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:
|
||||
|
||||
**Upgrade database to latest revision:**
|
||||
|
||||
``refstack-manage --config-file /path/to/refstack.conf upgrade --revision head``
|
||||
|
||||
**Check current revision:**
|
||||
|
||||
``refstack-manage --config-file /path/to/refstack.conf version``
|
||||
|
||||
::
|
||||
|
||||
Now it should be some revision number other than `None`.
|
||||
|
||||
(Optional) Generate About Page Content
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The RefStack About page is populated with HTML templates generated from
|
||||
our RST documentation files. If you want this information displayed, then
|
||||
run the following command from the root of the project.
|
||||
|
||||
``./tools/convert-docs.py -o ./refstack-ui/app/components/about/templates ./doc/source/*.rst``
|
||||
|
||||
Ignore any unknown directive errors.
|
||||
|
||||
Start RefStack
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
A simple way to start refstack is to just kick off gunicorn using the
|
||||
``refstack-api`` executable:
|
||||
|
||||
``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:
|
||||
|
||||
- ``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://<your server IP>:8000/v1/results/<test run id>`` with
|
||||
response JSON including the detail test results of the specified
|
||||
``<test run id>``
|
||||
|
||||
(Optional) Configure Foundation organization and group
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Overall RefStack admin access is given to users belonging to a
|
||||
"Foundation" organization. To become a Foundation admin, first a
|
||||
"Foundation" organization must be created. Note that you must have
|
||||
logged into RefStack at least once so that a user record for your
|
||||
account is created.
|
||||
|
||||
**Log into MySQL:**
|
||||
|
||||
``mysql -u root -p``
|
||||
|
||||
**Create a group for the "Foundation" organization:**
|
||||
|
||||
``INSERT INTO refstack.group (id, name, created_at) VALUES (UUID(), 'Foundation Group', NOW());``
|
||||
|
||||
**Get the group ID for the group you just created:**
|
||||
|
||||
``SELECT id from refstack.group WHERE name = 'Foundation Group';``
|
||||
|
||||
**Get your OpenID:**
|
||||
|
||||
``SELECT openid from refstack.user WHERE email = '<your email>';``
|
||||
|
||||
**Add your user account to the previously created "Foundation" group.**
|
||||
|
||||
Replace ``<Group ID>`` and ``<Your OpenID>`` with the values
|
||||
retrieved in the two previous steps:
|
||||
|
||||
``INSERT INTO refstack.user_to_group (created_by_user, user_openid, group_id, created_at) VALUES ('<Your OpenID>', '<Your OpenID>', '<Group ID>', NOW());``
|
||||
|
||||
**Create the actual "Foundation" organization using this group:**
|
||||
|
||||
``INSERT INTO refstack.organization (id, type, name, group_id, created_by_user, created_at) VALUES (UUID(), 0, 'Foundation', '<Group ID>', '<Your OpenID>', NOW());``
|
||||
|
||||
(Optional) Build documentation
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The RefStack documentation can be build using following commands:
|
||||
|
||||
``cd ~/refstack; source .venv/bin/activate``
|
||||
|
||||
``sudo apt-get install python3-dev python-tox``
|
||||
|
||||
``tox -e docs``
|
||||
|
||||
The documentation files will be build under ``~/refstack/build/sphinx``.
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
API configuration file preparation
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Make a copy of the sample config file (etc/refstack.conf.sample) and
|
||||
update it with the correct information of your environment. Examples
|
||||
of the config parameters with default values are included in the
|
||||
sample config file.
|
||||
|
||||
You should ensure that the following values in the config file are
|
||||
noted and properly set:
|
||||
|
||||
``connection`` field in the ``[database]``\ section.
|
||||
|
||||
For example, if the backend database is MySQL then update:
|
||||
|
||||
``#connection = <None>`` to
|
||||
``connection = mysql+pymysql://refstack:<your password>@x.x.x.x/refstack``
|
||||
|
||||
``ui_url`` field in the ``[DEFAULT]`` section.
|
||||
|
||||
This should be the URL that the UI can be accessed from. This will
|
||||
likely 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.
|
||||
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
(Optional) Build documentation
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The RefStack documentation can be build using following commands:
|
||||
|
||||
``cd ~/refstack; source .venv/bin/activate``
|
||||
|
||||
``sudo apt-get install python3-dev python-tox``
|
||||
|
||||
``tox -e docs``
|
||||
|
||||
The documentation files will be build under ``~/refstack/build/sphinx``.
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
Clone the repository
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
``git clone https://opendev.org/osf/refstack``
|
||||
|
||||
``cd refstack``
|
||||
|
||||
**Create virtual environment:**
|
||||
|
||||
``virtualenv .venv --system-site-package``
|
||||
|
||||
**Source to virtual environment:**
|
||||
|
||||
``source .venv/bin/activate``
|
||||
|
||||
**Update pip**
|
||||
|
||||
``pip install -U pip``
|
||||
|
||||
**Install environment pre-requirements**
|
||||
|
||||
# App server
|
||||
|
||||
``pip install gunicorn==18``
|
||||
|
||||
# python mysql connector
|
||||
|
||||
``pip install PyMySQL>=0.6.2,!=0.6.4``
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
(Optional) Configure Foundation organization and group
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Overall RefStack admin access is given to users belonging to a
|
||||
"Foundation" organization. To become a Foundation admin, first a
|
||||
"Foundation" organization must be created. Note that you must have
|
||||
logged into RefStack at least once so that a user record for your
|
||||
account is created.
|
||||
|
||||
**Log into MySQL:**
|
||||
|
||||
``mysql -u root -p``
|
||||
|
||||
**Create a group for the "Foundation" organization:**
|
||||
|
||||
``INSERT INTO refstack.group (id, name, created_at) VALUES (UUID(), 'Foundation Group', NOW());``
|
||||
|
||||
**Get the group ID for the group you just created:**
|
||||
|
||||
``SELECT id from refstack.group WHERE name = 'Foundation Group';``
|
||||
|
||||
**Get your OpenID:**
|
||||
|
||||
``SELECT openid from refstack.user WHERE email = '<your email>';``
|
||||
|
||||
**Add your user account to the previously created "Foundation" group.**
|
||||
|
||||
Replace ``<Group ID>`` and ``<Your OpenID>`` with the values
|
||||
retrieved in the two previous steps:
|
||||
|
||||
``INSERT INTO refstack.user_to_group (created_by_user, user_openid, group_id, created_at) VALUES ('<Your OpenID>', '<Your OpenID>', '<Group ID>', NOW());``
|
||||
|
||||
**Create the actual "Foundation" organization using this group:**
|
||||
|
||||
``INSERT INTO refstack.organization (id, type, name, group_id, created_by_user, created_at) VALUES (UUID(), 0, 'Foundation', '<Group ID>', '<Your OpenID>', NOW());``
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
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``
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
Database sync
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
**Check current revision:**
|
||||
|
||||
``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:
|
||||
|
||||
**Upgrade database to latest revision:**
|
||||
|
||||
``refstack-manage --config-file /path/to/refstack.conf upgrade --revision head``
|
||||
|
||||
**Check current revision:**
|
||||
|
||||
``refstack-manage --config-file /path/to/refstack.conf version``
|
||||
|
||||
::
|
||||
|
||||
Now it should be some revision number other than `None`.
|
||||
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
(Optional) Generate About Page Content
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The RefStack About page is populated with HTML templates generated from
|
||||
our RST documentation files. If you want this information displayed, then
|
||||
run the following command from the root of the project.
|
||||
|
||||
``./tools/convert-docs.py -o ./refstack-ui/app/components/about/templates ./doc/source/*.rst``
|
||||
|
||||
Ignore any unknown directive errors.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
Install API dependencies
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
``sudo apt-get install git python-dev python-virtualenv libssl-dev build-essential libffi-dev``
|
||||
|
||||
``sudo apt-get install mysql-server python-mysqldb``
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Install RefStack application
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
``pip install .``
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
Install needed RefStack UI library dependencies
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
``yarn``
|
||||
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
Install RefStack UI dependencies
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
``curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -``
|
||||
|
||||
``curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -``
|
||||
|
||||
``echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list``
|
||||
|
||||
``sudo apt-get update && sudo apt-get install -y nodejs yarn``
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
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
|
||||
`Openstackid project <https://opendev.org/osf/openstackid>`__ .
|
||||
You would then need to modify the ``openstack_openid_endpoint`` field in
|
||||
the ``[osid]`` section in refstack.conf to match the local endpoint.
|
||||
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
Setup the RefStack database
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
**Log into MySQL:**
|
||||
|
||||
``mysql -u root -p``
|
||||
|
||||
**After authentication, create the database:**
|
||||
|
||||
``CREATE DATABASE refstack;``
|
||||
|
||||
**Create a refstack user:**
|
||||
|
||||
``CREATE USER 'refstack'@'localhost' IDENTIFIED BY '<your password>';``
|
||||
|
||||
or using hash value for your password
|
||||
|
||||
``CREATE USER 'refstack'@'localhost' IDENTIFIED BY PASSWORD '<hash value of your password';``
|
||||
|
||||
**Grant privileges:**
|
||||
|
||||
``GRANT ALL PRIVILEGES ON refstack . * TO 'refstack'@'localhost';``
|
||||
|
||||
**Reload privileges:**
|
||||
|
||||
``FLUSH PRIVILEGES;``
|
||||
|
||||
**Exit MySQL:**
|
||||
|
||||
``quit``
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
Start RefStack
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
A simple way to start refstack is to just kick off gunicorn using the
|
||||
``refstack-api`` executable:
|
||||
|
||||
``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:
|
||||
|
||||
- ``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://<your server IP>:8000/v1/results/<test run id>`` with
|
||||
response JSON including the detail test results of the specified
|
||||
``<test run id>``
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
===================
|
||||
RefStack Quickstart
|
||||
===================
|
||||
|
||||
You can use docker for `one-click setup <run_in_docker.html>`__ or follow
|
||||
step-by-step instructions below. These instructions have been tested on
|
||||
Ubuntu 14 and 16 LTS.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:includehidden:
|
||||
|
||||
InstallApiDependencies
|
||||
InstallRefstackUiDependencies
|
||||
SetupTheRefstackDatabase
|
||||
CloneTheRepository
|
||||
InstallRefstackApplication
|
||||
InstallRefstackUILibrarys
|
||||
ApiConfigurationFilePreparation
|
||||
CreateUIConfigFile
|
||||
OpenstackOpenIdEndpointConfiguration
|
||||
DatabaseSync
|
||||
GenerateAboutPageContent
|
||||
StartRefstack
|
||||
ConfigureFoundationOrganizationAndGroups
|
||||
BuildDocumentation
|
||||
|
|
@ -1,6 +1,3 @@
|
|||
Run-in-docker manual
|
||||
====================
|
||||
|
||||
Option 1 - Using an ansible playbook
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
These steps are meant for RefStack developers to help them with setting up
|
||||
|
|
@ -31,7 +28,6 @@ and then restart the apache service so that it loads the new configuration::
|
|||
|
||||
$ systemctl restart apache2
|
||||
|
||||
|
||||
How to edit refstack files within the container
|
||||
-----------------------------------------------
|
||||
|
||||
|
|
@ -100,78 +96,3 @@ To see the server's logs use the following command::
|
|||
|
||||
$ docker container logs -f <container name>
|
||||
|
||||
|
||||
Option 2 - Using a script
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
NOTE: This is currently outdated, follow the Option 1 for now.
|
||||
|
||||
The main purpose of the ``run-in-docker`` script is to provide a
|
||||
convenient way to create a local setup of RefStack inside a Docker
|
||||
container. It should be helpful for new developers and also for testing
|
||||
new features.
|
||||
|
||||
Requirements:
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
- ``Docker >= 1.6`` (How to update on
|
||||
`Ubuntu <http://www.ubuntuupdates.org/ppa/docker>`__)
|
||||
|
||||
How to use:
|
||||
^^^^^^^^^^^
|
||||
|
||||
Just run the ``run-in-docker`` script, but is important to first set
|
||||
env[REFSTACK\_HOST] with the public host/IP for your local API. If you
|
||||
want to test RefStack with OpenStackid you should point a valid local
|
||||
alias here. For example:
|
||||
|
||||
``export REFSTACK_HOST=myrefstack.com``
|
||||
|
||||
By default 127.0.0.1 is used.
|
||||
|
||||
After it completes, check that the site is running on https://127.0.0.1.
|
||||
|
||||
The script will build a RefStack docker image with all dependencies, and
|
||||
will run a container from this image. By default, RefStack will run
|
||||
inside this container. You also can run ``run-in-docker bash`` to get
|
||||
access into the container. If you stop the RefStack server by pressing
|
||||
'Ctrl-C', the container is kept alive and will be re-used next time.
|
||||
|
||||
You can customize the RefStack API config by editing
|
||||
``docker/templates/refstack.conf.tmpl``. It is a bash template, so you
|
||||
can use ${SOME\_ENV\_VARIABLE} in it.
|
||||
|
||||
This script can make the reviewing process much easier because it
|
||||
creates separate containers for each review. Containers get names in the
|
||||
form refstack\_{REVIEW-TOPIC}. Database schema changes are automatically
|
||||
handled, too, where the script creates a data container for each
|
||||
database revision (refstack\_data\_{DATA-BASE-REVISON}) and reuses it
|
||||
where possible. For example, if a new review uses an existing database
|
||||
revision, that database container will be used.
|
||||
|
||||
Available script options:
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- ``-r`` Force delete the RefStack container and run it again. This
|
||||
will update the RefStack config from template noted above.
|
||||
- ``-i`` Run a container with isolated MySQL data. By default MySQL
|
||||
data is stored in a refstack\_data\_{DATA-BASE-REVISON} container. It
|
||||
reuses this container if such one exists. If you want to drop the DB
|
||||
data, just execute
|
||||
``sudo docker rm refstack_data_{DATA-BASE-REVISON}``.
|
||||
- ``-b`` Force delete RefStack image and build it again. This rebuilds
|
||||
the Python and JS environment for RefStack.
|
||||
- ``-d`` Turn on debug information.
|
||||
- ``-h`` Print usage message.
|
||||
|
||||
Useful in-container commands/aliases:
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- ``api-up`` - sync project and run the RefStack API
|
||||
- ``api-init-db`` - initialize the RefStack database
|
||||
- ``api-db-version`` - get current migration version of the RefStack
|
||||
database
|
||||
- ``api-sync`` - sync project files in the container with the project
|
||||
files on the host
|
||||
- ``activate`` - activate the python virtual env
|
||||
- ``mysql`` - open the MySQL console
|
||||
|
|
@ -0,0 +1,75 @@
|
|||
Option 2 - Using a script
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
NOTE: This is currently outdated, follow the Option 1 for now.
|
||||
|
||||
The main purpose of the ``run-in-docker`` script is to provide a
|
||||
convenient way to create a local setup of RefStack inside a Docker
|
||||
container. It should be helpful for new developers and also for testing
|
||||
new features.
|
||||
|
||||
Requirements:
|
||||
-------------
|
||||
|
||||
- ``Docker >= 1.6`` (How to update on
|
||||
`Ubuntu <http://www.ubuntuupdates.org/ppa/docker>`__)
|
||||
|
||||
How to use:
|
||||
-----------
|
||||
|
||||
Just run the ``run-in-docker`` script, but is important to first set
|
||||
env[REFSTACK\_HOST] with the public host/IP for your local API. If you
|
||||
want to test RefStack with OpenStackid you should point a valid local
|
||||
alias here. For example:
|
||||
|
||||
``export REFSTACK_HOST=myrefstack.com``
|
||||
|
||||
By default 127.0.0.1 is used.
|
||||
|
||||
After it completes, check that the site is running on https://127.0.0.1.
|
||||
|
||||
The script will build a RefStack docker image with all dependencies, and
|
||||
will run a container from this image. By default, RefStack will run
|
||||
inside this container. You also can run ``run-in-docker bash`` to get
|
||||
access into the container. If you stop the RefStack server by pressing
|
||||
'Ctrl-C', the container is kept alive and will be re-used next time.
|
||||
|
||||
You can customize the RefStack API config by editing
|
||||
``docker/templates/refstack.conf.tmpl``. It is a bash template, so you
|
||||
can use ${SOME\_ENV\_VARIABLE} in it.
|
||||
|
||||
This script can make the reviewing process much easier because it
|
||||
creates separate containers for each review. Containers get names in the
|
||||
form refstack\_{REVIEW-TOPIC}. Database schema changes are automatically
|
||||
handled, too, where the script creates a data container for each
|
||||
database revision (refstack\_data\_{DATA-BASE-REVISON}) and reuses it
|
||||
where possible. For example, if a new review uses an existing database
|
||||
revision, that database container will be used.
|
||||
|
||||
Available script options:
|
||||
-------------------------
|
||||
|
||||
- ``-r`` Force delete the RefStack container and run it again. This
|
||||
will update the RefStack config from template noted above.
|
||||
- ``-i`` Run a container with isolated MySQL data. By default MySQL
|
||||
data is stored in a refstack\_data\_{DATA-BASE-REVISON} container. It
|
||||
reuses this container if such one exists. If you want to drop the DB
|
||||
data, just execute
|
||||
``sudo docker rm refstack_data_{DATA-BASE-REVISON}``.
|
||||
- ``-b`` Force delete RefStack image and build it again. This rebuilds
|
||||
the Python and JS environment for RefStack.
|
||||
- ``-d`` Turn on debug information.
|
||||
- ``-h`` Print usage message.
|
||||
|
||||
Useful in-container commands/aliases:
|
||||
-------------------------------------
|
||||
|
||||
- ``api-up`` - sync project and run the RefStack API
|
||||
- ``api-init-db`` - initialize the RefStack database
|
||||
- ``api-db-version`` - get current migration version of the RefStack
|
||||
database
|
||||
- ``api-sync`` - sync project files in the container with the project
|
||||
files on the host
|
||||
- ``activate`` - activate the python virtual env
|
||||
- ``mysql`` - open the MySQL console
|
||||
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
====================
|
||||
Run-in-docker manual
|
||||
====================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:includehidden:
|
||||
|
||||
Option1AnsiblePlaybook
|
||||
Option2UsingAScript
|
||||
|
|
@ -1,8 +1,9 @@
|
|||
======================
|
||||
Test result management
|
||||
======================
|
||||
|
||||
Test result to product version association
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
------------------------------------------
|
||||
|
||||
Test results uploaded by users can be associated to a version of a product. To
|
||||
perform this association, the user must be both the one who uploaded the result
|
||||
|
|
@ -11,7 +12,7 @@ associated to a product, all admins of the vendor which owns the product can
|
|||
manage the test result.
|
||||
|
||||
Mark or unmark a test results as verified
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
-----------------------------------------
|
||||
|
||||
Only Foundation admins can mark and un-mark a test as verified. A verified
|
||||
test result can not be updated or deleted.
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
Product entity
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
Any user who has successfully authenticated to the RefStack server can create
|
||||
product entities. The minimum information needed to create a product entity is
|
||||
as follows:
|
||||
|
||||
- Name
|
||||
|
||||
This is the name of the product entity being created.
|
||||
|
||||
- Product type:
|
||||
|
||||
Product types are defined by OpenStack as shown on the OpenStack Marketplace
|
||||
( https://www.openstack.org/marketplace/ ). Currently, there are three types
|
||||
of products, namely: Distro & Appliances, Hosted Private Clouds and Public
|
||||
Clouds.
|
||||
|
||||
- Vendor
|
||||
|
||||
This is the vendor which owns the product. A default vendor will be created
|
||||
for the user if no vendor entity exists for this user.
|
||||
|
||||
Whenever a product is created, by default, it is a private product and is only
|
||||
visible to its vendor users. Vendor users can make a product publicly visible
|
||||
as needed later. However, only products that are owned by official vendors can
|
||||
be made publicly visible.
|
||||
|
||||
Product version
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
A default version is created whenever a product is created. The name of the
|
||||
default version is blank. The default version is used for products that have
|
||||
no version. Users can add new product versions to the product as needed.
|
||||
|
||||
43
doc/source/vendor_product.rst → doc/source/vendor_product_management/VendorEntity.rst
Executable file → Normal file
43
doc/source/vendor_product.rst → doc/source/vendor_product_management/VendorEntity.rst
Executable file → Normal file
|
|
@ -1,12 +1,3 @@
|
|||
Vendor and product management
|
||||
=============================
|
||||
|
||||
RefStack has implemented a vendor and product registration process so that test
|
||||
results can be associated to products of vendors. The creation and management
|
||||
of vendor and product entities can be done using the RefStack Server UI or
|
||||
RefStack APIs. The following is a quick guide outlining the information related
|
||||
to the creation and management of those entities.
|
||||
|
||||
Vendor entity
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -55,37 +46,3 @@ There are four types of vendor entities in RefStack:
|
|||
type will be changed from "pending" to "official". Official vendors are
|
||||
visible to all RefStack users.
|
||||
|
||||
Product entity
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
Any user who has successfully authenticated to the RefStack server can create
|
||||
product entities. The minimum information needed to create a product entity is
|
||||
as follows:
|
||||
|
||||
- Name
|
||||
|
||||
This is the name of the product entity being created.
|
||||
|
||||
- Product type:
|
||||
|
||||
Product types are defined by OpenStack as shown on the OpenStack Marketplace
|
||||
( https://www.openstack.org/marketplace/ ). Currently, there are three types
|
||||
of products, namely: Distro & Appliances, Hosted Private Clouds and Public
|
||||
Clouds.
|
||||
|
||||
- Vendor
|
||||
|
||||
This is the vendor which owns the product. A default vendor will be created
|
||||
for the user if no vendor entity exists for this user.
|
||||
|
||||
Whenever a product is created, by default, it is a private product and is only
|
||||
visible to its vendor users. Vendor users can make a product publicly visible
|
||||
as needed later. However, only products that are owned by official vendors can
|
||||
be made publicly visible.
|
||||
|
||||
Product version
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
A default version is created whenever a product is created. The name of the
|
||||
default version is blank. The default version is used for products that have
|
||||
no version. Users can add new product versions to the product as needed.
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
=============================
|
||||
Vendor and product management
|
||||
=============================
|
||||
|
||||
RefStack has implemented a vendor and product registration process so that test
|
||||
results can be associated to products of vendors. The creation and management
|
||||
of vendor and product entities can be done using the RefStack Server UI or
|
||||
RefStack APIs. The following is a quick guide outlining the information related
|
||||
to the creation and management of those entities.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:includehidden:
|
||||
|
||||
VendorEntity
|
||||
ProductEntity
|
||||
3
tox.ini
3
tox.ini
|
|
@ -49,7 +49,8 @@ commands = {posargs}
|
|||
commands = {toxinidir}/tools/cover.sh {posargs}
|
||||
|
||||
[testenv:docs]
|
||||
deps = -r{toxinidir}/doc/requirements.txt
|
||||
deps = -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
|
||||
-r{toxinidir}/doc/requirements.txt
|
||||
commands = sphinx-build -b html doc/source doc/build/html
|
||||
|
||||
[flake8]
|
||||
|
|
|
|||
Loading…
Reference in New Issue