From 2f7b9ebd7cd7eda4147a1e9f96cacd61e8c956c0 Mon Sep 17 00:00:00 2001 From: David Blum Date: Mon, 25 Nov 2024 12:55:31 -0800 Subject: [PATCH] Updates to user guide --- docs/user_guide/source/api.rst | 7 +- docs/user_guide/source/conf.py | 10 +-- docs/user_guide/source/getting_started.rst | 99 ++++++++++++---------- web/01_software.md | 9 +- 4 files changed, 67 insertions(+), 58 deletions(-) diff --git a/docs/user_guide/source/api.rst b/docs/user_guide/source/api.rst index 7c82ab131..e1b142f3c 100644 --- a/docs/user_guide/source/api.rst +++ b/docs/user_guide/source/api.rst @@ -2,10 +2,9 @@ API Summary =========== -To interact with a deployed test case, use the API defined in the sections below by sending RESTful requests as follows: - -- If Single Test Case on Local Computing Resource, send API requests to localhost port 5000 as ``http://127.0.0.1:5000/``. -- If using Public Web Service, send API requests to ``//``, where ```` is your returned testid upon test case selection. See the section Getting Started for more information. +After accessing BOPTEST and deploying a test case as described in the Getting Started section, +interact with a deployed test case using the API defined in the sections below by sending HTTP RESTful requests. +Note that you will need to prepend the request url with the base url and append the request with the ``testid`` as described in the Getting Started section. Each API request will return a JSON in the form ``{"status":, "message":, "payload":}``, where: diff --git a/docs/user_guide/source/conf.py b/docs/user_guide/source/conf.py index 695cc81ad..5cb402e93 100755 --- a/docs/user_guide/source/conf.py +++ b/docs/user_guide/source/conf.py @@ -45,7 +45,7 @@ master_doc = 'index' # General information about the project. -project = u'BOPTEST User Guide v0.6.0' +project = u'BOPTEST User Guide v0.7.0' copyright = u'' author = u'' @@ -56,7 +56,7 @@ # The short X.Y version. #version = u'0.1' # The full version, including alpha/beta/rc tags. -release = u'0.6.0' +release = u'0.7.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -238,7 +238,7 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'BOPTESTUserGuide.tex', u'BOPTEST User Guide v0.6.0', + (master_doc, 'BOPTESTUserGuide.tex', u'BOPTEST User Guide v0.7.0', u'', 'manual'), ] @@ -268,7 +268,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'BOPTESTUserGuide', u'BOPTEST User Guide v0.6.0', + (master_doc, 'BOPTESTUserGuide', u'BOPTEST User Guide v0.7.0', [author], 1) ] @@ -282,7 +282,7 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'BOPTESTUserGuide', u'BOPTEST User Guide v0.6.0', + (master_doc, 'BOPTESTUserGuide', u'BOPTEST User Guide v0.7.0', author, 'BOPTESTUserGuide', 'One line description of project.', 'Miscellaneous'), ] diff --git a/docs/user_guide/source/getting_started.rst b/docs/user_guide/source/getting_started.rst index d007645f1..575f98e84 100644 --- a/docs/user_guide/source/getting_started.rst +++ b/docs/user_guide/source/getting_started.rst @@ -8,72 +8,79 @@ Using BOPTEST There are two ways you can access BOPTEST, depending on your preference: -1. **Single Test Case on Local Computing Resource**: Deploy a single test -case on your local computing resource and interact with it at localhost +**I. Deploy on Local Computing Resource**: Deploy BOPTEST +on your local computing resource and localhost, deploy a test case, and interact with it via the BOPTEST API. -2. **Public Web-Service**: Utilize a web-hosted BOPTEST -environment (BOPTEST-Service) available to the public to deploy a test case in the cloud and +**II. Utilize Public Web-Service**: Utilize a publicly available web-hosted BOPTEST +environment (BOPTEST-Service) to deploy a test case in the cloud and interact with it at a URL specific to you via the BOPTEST API. -Single Test Case on Local Computing Resource -============================================ +I. Deploy on Local Computing Resource +===================================== -Installation ------------- -1. Install Docker and docker-compose on your system. -2. Download the latest version of BOPTEST as a .zip and extract it to a location. +1. Installation +--------------- +- Install Docker (https://docs.docker.com/get-docker/) on your system. +- Download the latest version of BOPTEST as a .zip and extract it to a location. -Deploy a Test Case ------------------- -Within the root directory of the extracted software, use the following commands: +2. Deploy a Test Case +--------------------- +Use Docker to build and deploy BOPTEST. In the root of the repository, run the command below. -- Linux or macOS: ``$ TESTCASE= docker-compose up`` -- Windows PowerShell: ``> ($env:TESTCASE="") -and (docker-compose up)`` +- ``docker compose up web worker provision`` +- If you want to be able to deploy multiple test cases at the same time, append the argument ``--scale worker=n`` where ``n`` equals the number of test cases you want to be able to have running at the same time. -A couple notes: +Then, send the following API request to url ``http://127.0.0.1:80``. -- Replace ```` with the name of the test case you wish to deploy. -- The first time this command is run, the image ``boptest_base`` will be built. This takes about a minute. Subsequent usage will use the already-built image and deploy much faster. -- If you update your BOPTEST repository, use the command ``docker rmi boptest_base`` to remove the image so it can be re-built with the updated repository upon next deployment. -- ``TESTCASE`` is simply an environment variable. Consistent with use of docker-compose, you may also edit the value of this variable in the ``.env`` file and then use ``docker-compose up``. +- ``POST /testcases//select``, where ```` is replaced with the name of the test case you wish to deploy. +- The return will be a json with ``{'testid': }``. +- The returned ```` will be needed for all future API requests associated with your chosen test case. + +3. Use the API +-------------- +Send API requests to ``//``, where ```` is returned from the previous step. +See the section on API Summary for more information on available requests. + +4. Stop the Test Case +--------------------- +To stop the test case and free up the associated worker, send the following API request: +- ``PUT /stop/`` +- The test case will be stopped automatically in case of a period of inactivity. If this happens, a new test case should be deployed using the actions described previously. -Use the API ------------ -Send API requests to localhost port 5000 as ``http://127.0.0.1:5000/``. See the section API Summary for more information on available requests. +5. Shutdown BOPTEST +------------------- +Shutdown BOPTEST by the following command executed in the root directory of the repository: -Stop the Test Case ------------------- -Within the root directory of the extracted software, use the command ``docker-compose down``. +- ``docker compose down`` +- IMPORTANT: This is the best and most complete way to shutdown BOPTEST to prevent issues upon redeployment. -Public Web-Service -================== +II. Utilize Public Web-Service +============================== -Installation ------------- +1. Installation +--------------- There are no installation requirements. -Deploy a Test Case ------------------- +2. Deploy a Test Case +--------------------- Send the following API request to url ``https://api.boptest.net``. -- POST ``/testcases//select``, where ```` is replaced with the name of the test case you wish to deploy. +- ``POST /testcases//select``, where ```` is replaced with the name of the test case you wish to deploy. - The return will be a json with ``{'testid': }``. +- The returned ```` will be needed for all future API requests associated with your chosen test case. -The returned ```` will be needed for all future API requests associated -with your chosen test case. - -Use the API ------------ +3. Use the API +-------------- Send API requests to ``//``, where ```` is returned from the previous step. -See the section API Summary for more information on available requests. - -Stop the Test Case ------------------- -Send the following API request: ``/stop/``. -Note that the test case will be stopped automatically in case of a period of -inactivity. If this happens, a new test case should be deployed -using the actions described previously. +See the section on API Summary for more information on available requests. + +4. Stop the Test Case +--------------------- +To stop the test case, send the following API request: + +- ``PUT /stop/`` +- The test case will be stopped automatically in case of a period of inactivity. If this happens, a new test case should be deployed using the actions described previously. diff --git a/web/01_software.md b/web/01_software.md index 59d2e45e4..f639250e3 100644 --- a/web/01_software.md +++ b/web/01_software.md @@ -8,6 +8,7 @@ hero_height: is-fullwidth # Download the Latest BOPTEST Software The latest version is ``v0.7.0``, released on November 25, 2024. +- **Note**: Important software architecture changes were made in this latest release as described in the [release notes](https://github.com/ibpsa/project1-boptest/releases/tag/v0.7.0), which makes BOPTEST-Service the only deployment architecture. Click the button below to download the latest version as a zip file. @@ -21,11 +22,13 @@ To access the latest development version or contribute to the project, go to the GitHub -# Use BOPTEST-Service +# Use Public Web-Service -Use a web-hosted instance of BOPTEST that provides the functionality of BOPTEST ``v0.6.0`` as a web-service without the need to download or install anything locally. +Use a publicly available web-hosted instance of BOPTEST that provides the functionality of BOPTEST ``v0.6.0`` as a web-service without the need to download or install anything locally. -Get started with the [User Guide](/docs-userguide/index.html). +Get started with the [User Guide](/docs-userguide/index.html) and [Training](/project1-boptest/training/index.html). + +Then, check out the available [Test Cases](/project1-boptest/testcases/index.html). For more information, to access the latest development version of the web-service software, or contribute, go to the GitHub repository.