diff --git a/doc/source/conf.py b/doc/source/conf.py index e847034b..a087cc59 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -56,7 +56,7 @@ version = '1.0' release = '1.0' # openstackdocstheme options -repository_name = 'openstack/refstack' +openstackdocs_repo_name = 'openinfra/refstack' bug_project = '878' bug_tag = '' @@ -103,7 +103,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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 32ce225d..c043a5e9 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -7,38 +7,16 @@ Welcome to RefStack's documentation! ==================================== --------------- -About RefStack --------------- +.. include:: README.rst -.. toctree:: - :maxdepth: 2 - - README - --------------------------- -Installing RefStack Server --------------------------- +Content: +-------- .. toctree:: :maxdepth: 2 refstack - run_in_docker - --------------- -Using RefStack --------------- - -.. toctree:: - :maxdepth: 2 - + run_in_docker/index + vendor_product_management/index uploading_private_results - vendor_product test_result_management - ------------------- -Indices and tables ------------------- - -* :ref:`search` diff --git a/doc/source/refstack.rst b/doc/source/refstack.rst index a282a15d..ccabfcb1 100644 --- a/doc/source/refstack.rst +++ b/doc/source/refstack.rst @@ -1,3 +1,4 @@ +=================== RefStack Quickstart =================== @@ -7,90 +8,86 @@ 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`` + 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`` + 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:** +**Log into MySQL**:: -``mysql -u root -p`` + mysql -u root -p -**After authentication, create the database:** +**After authentication, create the database**:: -``CREATE DATABASE refstack;`` + CREATE DATABASE refstack; -**Create a refstack user:** +**Create a refstack user**:: -``CREATE USER 'refstack'@'localhost' IDENTIFIED BY '';`` + CREATE USER 'refstack'@'localhost' IDENTIFIED BY ''; -or using hash value for your password +**or using hash value for your password**:: -``CREATE USER 'refstack'@'localhost' IDENTIFIED BY PASSWORD '=0.6.2,!=0.6.4`` + pip install gunicorn==18 # App server + pip install PyMySQL>=0.6.2,!=0.6.4 # python mysql connector Install RefStack application ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:: -``pip install .`` + pip install . Install needed RefStack UI library dependencies ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:: -``yarn`` + yarn API configuration file preparation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -136,9 +133,9 @@ 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"}: +{"refstackApiUrl": "http://192.168.56.101:8000/v1"}:: -``cp refstack-ui/app/config.json.sample refstack-ui/app/config.json`` + cp refstack-ui/app/config.json.sample refstack-ui/app/config.json Openstack OpenID endpoint configuration (optional) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -188,21 +185,21 @@ the ``[osid]`` section in refstack.conf to match the local endpoint. Database sync ^^^^^^^^^^^^^ -**Check current revision:** +**Check current revision**:: -``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: -**Upgrade database to latest revision:** +**Upgrade database to latest revision**:: -``refstack-manage --config-file /path/to/refstack.conf upgrade --revision head`` + refstack-manage --config-file /path/to/refstack.conf upgrade --revision head -**Check current revision:** +**Check current revision**:: -``refstack-manage --config-file /path/to/refstack.conf version`` + refstack-manage --config-file /path/to/refstack.conf version :: @@ -215,7 +212,9 @@ 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`` +:: + + ./tools/convert-docs.py -o ./refstack-ui/app/components/about/templates ./doc/source/*.rst Ignore any unknown directive errors. @@ -223,9 +222,9 @@ Start RefStack ^^^^^^^^^^^^^^ A simple way to start refstack is to just kick off gunicorn using the -``refstack-api`` executable: +``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. @@ -255,42 +254,41 @@ Overall RefStack admin access is given to users belonging to a logged into RefStack at least once so that a user record for your account is created. -**Log into MySQL:** +**Log into MySQL**:: -``mysql -u root -p`` + mysql -u root -p -**Create a group for the "Foundation" organization:** +**Create a group for the "Foundation" organization**:: -``INSERT INTO refstack.group (id, name, created_at) VALUES (UUID(), 'Foundation Group', NOW());`` + INSERT INTO refstack.group (id, name, created_at) VALUES (UUID(), 'Foundation Group', NOW()); -**Get the group ID for the group you just created:** +**Get the group ID for the group you just created**:: -``SELECT id from refstack.group WHERE name = 'Foundation Group';`` + SELECT id from refstack.group WHERE name = 'Foundation Group'; -**Get your OpenID:** +**Get your OpenID**:: -``SELECT openid from refstack.user WHERE email = '';`` + SELECT openid from refstack.user WHERE email = ''; **Add your user account to the previously created "Foundation" group.** Replace ```` and ```` with the values -retrieved in the two previous steps: +retrieved in the two previous steps:: -``INSERT INTO refstack.user_to_group (created_by_user, user_openid, group_id, created_at) VALUES ('', '', '', NOW());`` + INSERT INTO refstack.user_to_group (created_by_user, user_openid, group_id, created_at) VALUES ('', '', '', NOW()); -**Create the actual "Foundation" organization using this group:** +**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', '', '', NOW());`` + INSERT INTO refstack.organization (id, type, name, group_id, created_by_user, created_at) VALUES (UUID(), 0, 'Foundation', '', '', NOW()); (Optional) Build documentation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The RefStack documentation can be build using following commands: +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`` + 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``. + diff --git a/doc/source/run_in_docker.rst b/doc/source/run_in_docker/Option1AnsiblePlaybook.rst similarity index 51% rename from doc/source/run_in_docker.rst rename to doc/source/run_in_docker/Option1AnsiblePlaybook.rst index b57ac748..bc39f038 100644 --- a/doc/source/run_in_docker.rst +++ b/doc/source/run_in_docker/Option1AnsiblePlaybook.rst @@ -1,8 +1,6 @@ -Run-in-docker manual -==================== - +==================================== Option 1 - Using an ansible playbook -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==================================== These steps are meant for RefStack developers to help them with setting up a local refstack instance. @@ -31,7 +29,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 +97,3 @@ To see the server's logs use the following command:: $ docker container logs -f - -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 `__) - -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 diff --git a/doc/source/run_in_docker/Option2UsingAScript.rst b/doc/source/run_in_docker/Option2UsingAScript.rst new file mode 100644 index 00000000..052ef08c --- /dev/null +++ b/doc/source/run_in_docker/Option2UsingAScript.rst @@ -0,0 +1,76 @@ +========================= +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 `__) + +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 + diff --git a/doc/source/run_in_docker/index.rst b/doc/source/run_in_docker/index.rst new file mode 100644 index 00000000..9a174f79 --- /dev/null +++ b/doc/source/run_in_docker/index.rst @@ -0,0 +1,9 @@ +Run-in-docker manual +==================== + +.. toctree:: + :maxdepth: 1 + :includehidden: + + Option1AnsiblePlaybook + Option2UsingAScript diff --git a/doc/source/test_result_management.rst b/doc/source/test_result_management.rst index d11b0a7a..be40c8c4 100755 --- a/doc/source/test_result_management.rst +++ b/doc/source/test_result_management.rst @@ -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. diff --git a/doc/source/uploading_private_results.rst b/doc/source/uploading_private_results.rst index 5ad6fa59..cf336fb6 100644 --- a/doc/source/uploading_private_results.rst +++ b/doc/source/uploading_private_results.rst @@ -1,3 +1,4 @@ +====================================== How to upload test results to RefStack ====================================== diff --git a/doc/source/vendor_product_management/ProductEntity.rst b/doc/source/vendor_product_management/ProductEntity.rst new file mode 100644 index 00000000..e08b60e2 --- /dev/null +++ b/doc/source/vendor_product_management/ProductEntity.rst @@ -0,0 +1,36 @@ +============== +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. + diff --git a/doc/source/vendor_product.rst b/doc/source/vendor_product_management/VendorEntity.rst old mode 100755 new mode 100644 similarity index 50% rename from doc/source/vendor_product.rst rename to doc/source/vendor_product_management/VendorEntity.rst index 2ba919b3..94c2410e --- a/doc/source/vendor_product.rst +++ b/doc/source/vendor_product_management/VendorEntity.rst @@ -1,14 +1,6 @@ -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 -^^^^^^^^^^^^^ +============= Any user who has successfully authenticated to the RefStack server can create vendor entities. The minimum required information to create a vendor is the @@ -55,37 +47,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. diff --git a/doc/source/vendor_product_management/index.rst b/doc/source/vendor_product_management/index.rst new file mode 100644 index 00000000..3fc73afd --- /dev/null +++ b/doc/source/vendor_product_management/index.rst @@ -0,0 +1,15 @@ +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 diff --git a/tox.ini b/tox.ini index 0dfcd257..d623dc21 100644 --- a/tox.ini +++ b/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]