From: Lott, Christopher (cl778h) Date: Tue, 21 Apr 2020 12:22:36 +0000 (-0400) Subject: Update RIC Dashboard documentation X-Git-Tag: 2.0.2~6 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=ba6910074f6c51f9b391ef7651b7a87d527593bd;p=portal%2Fric-dashboard.git Update RIC Dashboard documentation Add user guide with screen shots. Change-Id: Id21363b9d8d09312b9d7821a29ce9d46c01ae79e Issue-ID: OAM-102 Signed-off-by: Lott, Christopher (cl778h) --- diff --git a/docs/_static/dashboard-v2-catalog.png b/docs/_static/dashboard-v2-catalog.png new file mode 100644 index 00000000..0008b33a Binary files /dev/null and b/docs/_static/dashboard-v2-catalog.png differ diff --git a/docs/_static/dashboard-v2-control.png b/docs/_static/dashboard-v2-control.png new file mode 100644 index 00000000..09521a66 Binary files /dev/null and b/docs/_static/dashboard-v2-control.png differ diff --git a/docs/_static/dashboard-v2-instance.png b/docs/_static/dashboard-v2-instance.png new file mode 100644 index 00000000..99b2f9b4 Binary files /dev/null and b/docs/_static/dashboard-v2-instance.png differ diff --git a/docs/_static/dashboard-v2-main.png b/docs/_static/dashboard-v2-main.png new file mode 100644 index 00000000..cacfb352 Binary files /dev/null and b/docs/_static/dashboard-v2-main.png differ diff --git a/docs/_static/dashboard-v2-menu.png b/docs/_static/dashboard-v2-menu.png new file mode 100644 index 00000000..181b461d Binary files /dev/null and b/docs/_static/dashboard-v2-menu.png differ diff --git a/docs/_static/dashboard-v2-platform-stats.png b/docs/_static/dashboard-v2-platform-stats.png new file mode 100644 index 00000000..5f41c006 Binary files /dev/null and b/docs/_static/dashboard-v2-platform-stats.png differ diff --git a/docs/_static/dashboard-v2-pods.png b/docs/_static/dashboard-v2-pods.png new file mode 100644 index 00000000..2e3bba76 Binary files /dev/null and b/docs/_static/dashboard-v2-pods.png differ diff --git a/docs/config-deploy.rst b/docs/config-deploy.rst index ddf164f9..16db1e9b 100644 --- a/docs/config-deploy.rst +++ b/docs/config-deploy.rst @@ -37,15 +37,6 @@ deployment-specific configuration. The properties are listed below in alphabetical order. -``a1med.url.prefix`` - -A1 Mediator URL prefix. No useful default. Usually a service name -like ``http://ricplt-entry/a1mediator`` - -``a1med.url.suffix`` - -A1 Mediator URL suffix. Default is the empty string. - ``appmgr.url.prefix`` Application Manager URL prefix. No useful default. Usually a service @@ -119,17 +110,22 @@ Name of request cookie with user ID. Default is ``UserId``. REST user name expected at ONAP portal. No default value. +``ricinstances.regions`` + +List of RIC region entries. Each region has a name and a list of RIC +instances. See the application.yaml file for an example. + ``server.port`` Port where the Tomcat server listens for requests. Default is ``8080``. -``metrics.url.ac`` +``statsfile`` -Url to the kibana source which visualizes AC App metrics. No default value and needs to be replaced with actual value during deployment time. +Path of file that stores application statistic details. Default is ``dashboard-stats.json``. ``userfile`` -Path of file that stores user details. Default is ``users.json``. +Path of file that stores user details. Default is ``dashboard-users.json``. Key Properties @@ -231,6 +227,6 @@ After creating, populating and mounting Kubernetes config maps appropriately, launch the server with this command-line invocation to include the ``config`` directory on the Java classpath:: - java -cp config:target/ric-dash-be-1.2.0-SNAPSHOT.jar \ + java -cp config:target/ric-dash-be-2.0.1-SNAPSHOT.jar \ -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \ org.springframework.boot.loader.PropertiesLauncher diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst index e7812943..d518948b 100644 --- a/docs/developer-guide.rst +++ b/docs/developer-guide.rst @@ -5,8 +5,8 @@ RIC Dashboard Developer Guide ============================= -This document provides a quickstart for developers of the O-RAN SC RIC Dashboard web -application. +This document provides a quickstart for developers of the O-RAN SC RIC +Dashboard web application. Prerequisites ------------- @@ -14,12 +14,14 @@ Prerequisites 1. Java development kit (JDK), version 11 or later 2. Maven dependency-management tool, version 3.4 or later -Other required tools including the Node Package Manager (npm) are fetched dynamically. +Other required tools including the Node Package Manager (npm) are +fetched dynamically. Clone and Update Submodules --------------------------- -After cloning the repository, initialize and update all git submodules like this:: +After cloning the repository, initialize and update all git submodules +like this:: git submodule init git submodule update @@ -32,14 +34,15 @@ Check the submodule status at any time like this:: Angular Front-End Application ----------------------------- -The Angular 8 application files are in subdirectory ``webapp-frontend``. -Build the front-end application via ``mvn package``. For development and debugging, -build the application, then launch an ng development server using this command:: +The Angular 8 application files are in subdirectory +``webapp-frontend``. Build the front-end application via ``mvn +package``. For development and debugging, build the application, then +launch an ng development server using this command:: ./ng serve --proxy-config proxy.conf.json -The app will automatically reload in the browser if you change any of the source files. -The ng server listens for requests at this URL: +The app will automatically reload in the browser if you change any of +the source files. The ng server listens for requests at this URL: http://localhost:4200 @@ -47,14 +50,14 @@ The ng server listens for requests at this URL: Spring-Boot Back-End Application -------------------------------- -A development (not production) server uses local configuration and serves mock data -that simulates the behavior of remote endpoints. The back-end server listens for -requests at this URL: +A development (not production) server uses local configuration and +serves mock data that simulates the behavior of remote endpoints. The +back-end server listens for requests at this URL: http://localhost:8080 -The directory ``src/test/resources`` contains usable versions of the required property -files. These steps are required to launch: +The directory ``src/test/resources`` contains usable versions of the +required property files. These steps are required to launch: 1. Install all project jar files locally 2. Set an environment variable via JVM argument: ``-Dorg.oransc.ric.portal.dashboard=mock`` @@ -68,23 +71,24 @@ These steps can be done with these commands:: Development user authentication ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The development server requires basic HTTP user authentication for all requests. Like -the production server, it requires HTTP headers with authentication for Portal API -requests. The username and password are stored in constants in this Java class in -the ``src/test/java`` folder:: +The development server requires basic HTTP user authentication for all +requests. Like the production server, it requires HTTP headers with +authentication for Portal API requests. The username and password are +stored in constants in this Java class in the ``src/test/java`` +folder:: org.oransc.ric.portal.dashboard.config.WebSecurityMockConfiguration -Like the production server, the development server also performs role-based -authentication on requests. The user name-role name associations are also defined -in the class shown above. +Like the production server, the development server also performs +role-based authentication on requests. The user name-role name +associations are also defined in the class shown above. Production user authentication ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The server uses the ONAP Portal's "EPSDK-FW" library to support a -single-sign-on (SSO) feature, which requires users to authenticate -at the ONAP Portal UI. The RIC Dashboard can be on-boarded as an +single-sign-on (SSO) feature, which requires users to authenticate at +the ONAP Portal UI. The RIC Dashboard can be on-boarded as an application on the ONAP Portal using its application on-boarding UI. The server authenticates requests using cookies that are set @@ -98,10 +102,10 @@ using a secret key shared with the ONAP Portal to yield a user ID. That ID must match a user's loginId defined in the user manager. The regular server checks requests for the following granted -authorities (role names), as defined in the java class ``DashboardConstants``. -A standard user can invoke all "GET" methods but not make changes. -A system administrator can invoke all methods ("GET", "POST", "PUT", -"DELETE") to make arbitrary changes:: +authorities (role names), as defined in the java class +``DashboardConstants``. A standard user can invoke all "GET" methods +but not make changes. A system administrator can invoke all methods +("GET", "POST", "PUT", "DELETE") to make arbitrary changes:: Standard_User System_Administrator diff --git a/docs/index.rst b/docs/index.rst index 547f782b..0335dc85 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,6 +17,7 @@ RIC Dashboard overview.rst config-deploy.rst developer-guide.rst + user-guide.rst release-notes.rst * :ref:`search` diff --git a/docs/overview.rst b/docs/overview.rst index 77e12209..d95f7c37 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -13,40 +13,26 @@ a Java (version 11) Spring-Boot (version 2.1) back end. Project Resources ----------------- -The source code is available from the Linux Foundation Gerrit server: - - ``_ - -The build (CI) jobs are in the Linux Foundation Jenkins server: +The project uses the following Linux Foundation resources. +* The source code is maintained in this Gerrit: + ``_ +* The build (CI) jobs are in this Jenkins: ``_ +* Issues are tracked in this Jira: + ``_ +* Project information is available in this Wiki: + ``_ -Issues are tracked in the Linux Foundation Jira server: - - ``_ - -Project information is available in the Linux Foundation Wiki: - - ``_ +Managed Resources +----------------- -A1 Mediator ------------ - -The Dashboard interfaces with the A1 Mediator. This platform -component is accessed via HTTP/REST requests using a client that is -generated from an API specification published by the A1 Mediator team. - -The A1 Mediator supports fetching and storing configuration of -applications, which is referred to as getting or setting a policy. -The Dashboard UI provides screens to view and modify configuration -data for such applications. As of this writing, the only application -that is managed via the A1 Mediator interface is the Admission Control -("AC") application. - +The RIC Dashboard is used to manage the following RIC Platform and RIC +xApplication components. Application Manager -------------------- +~~~~~~~~~~~~~~~~~~~ The Dashboard interfaces with the Application Manager. This platform component is accessed via HTTP/REST requests using a client that is @@ -59,7 +45,7 @@ for these functions. E2 Manager ----------- +~~~~~~~~~~ The Dashboard interfaces with the E2 Manager. This platform component is accessed via HTTP/REST requests using a client that is diff --git a/docs/user-guide.rst b/docs/user-guide.rst new file mode 100644 index 00000000..110f4a93 --- /dev/null +++ b/docs/user-guide.rst @@ -0,0 +1,80 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2020 AT&T Intellectual Property + +RIC Dashboard User Guide +======================== + +This document provides a quickstart for users of the O-RAN SC RIC +Dashboard web application. + + +Main Page +--------- + +The main (home) page has tiles for catalog, control and application +statistics, which are the main three areas of the Dashboard. A screen +shot of the main page is shown below. + +.. image:: _static/dashboard-v2-main.png + + +Left Menu +--------- + +Items on the left menu give access to all features of the RIC +Dashboard A screen shot of the menu is shown below. + +.. image:: _static/dashboard-v2-menu.png + + +xRIC Instances +-------------- + +The Dashboard can be configured to manage multiple RIC instances. +Instances are grouped into regions. Users can select the instance to +manage by clicking on the button shown at the bottom right of the main +page, which brings up the dialog shown below. + +.. image:: _static/dashboard-v2-instance.png + + +xApp Catalog +------------ + +The catalog page shows all the applications that can be deployed to +the RIC. Users may change static settings or deploy an application +form this page. A sample screen shot is shown below. + +.. image:: _static/dashboard-v2-catalog.png + + +RIC Control +----------- + +The control page shows the current RAN connections and the +applications deployed to the RIC. Users may disconnect the RIC, adjust +dynamic application settings and undeploy applications. A sample +screen shot is shown below. + +.. image:: _static/dashboard-v2-control.png + + +Platform Status +--------------- + +The cluster pods view shows the Kubernetes pod details. A sample +screen shot is shown below. + +.. image:: _static/dashboard-v2-pods.png + + +Platform Statistic Views +------------------------ + +The stats page allows configuration of views that analyze and display +statistics gathered by a remote system for applications deployed to +the RIC. Users may add or remove views. A sample screen shot is shown +below. + +.. image:: _static/dashboard-v2-platform-stats.png