From: Lott, Christopher (cl778h) Date: Wed, 14 Aug 2019 14:16:44 +0000 (-0400) Subject: Add RST documentation X-Git-Tag: R2~44 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=448fac1c4e8444418f9674585ecf958bc6c98df5;p=portal%2Fric-dashboard.git Add RST documentation Add overview of supported components and applications. Move README.md content to developer's guide. Change-Id: I8bcd519c041a73a645007ac289d771e92be29c43 Signed-off-by: Lott, Christopher (cl778h) --- diff --git a/README.md b/README.md index e70617f5..52bf7d73 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,14 @@ # O-RAN-SC RIC Dashboard Web Application -The O-RAN SC RIC Dashboard provides administrative and operator functions -for a disaggregated radio access network (RAN) controller. -The web app is built as a single-page app using an Angular 8 front end -and a Spring-Boot 2 back end. +The O-RAN SC RIC Dashboard provides administrative and operator +functions for a radio access network (RAN) controller. +This web app consists of an Angular (version 8) front end +and a Java (version 11) Spring-Boot (version 2.1) back end. -## Deployment configuration +Please see the documentation in the docs/ folder. -The application expects the following configuration files, -usually mounted as files from Kubernetes configuration maps: - - application.properties (in launch directory) - key.properties (on classpath) - portal.properties (on classpath) - -Sample files are in directory src/main/resources and src/test/resources. - -## Development guide - -This section gives a quickstart guide for developers. - -### Prerequisites - -1. Java development kit (JDK), version 11 or later -2. Maven dependency-management tool, version 3.4 or later - -### Build and launch the web app - -Instructions for launching a backend Sprint-Boot server -are available in the webapp-backend README file. -After launching, open a browser on http://localhost:8080 - -Instructions for launching a frontend Angular server (only for development) -are available in the webapp-frontend README file. -After launching, open a browser on http://localhost:4200 +The backend server publishes live API documentation at the +URL `http://your-host-name-here:8080/swagger-ui.html` ## License diff --git a/docs/config-deploy.rst b/docs/config-deploy.rst new file mode 100644 index 00000000..d89aae93 --- /dev/null +++ b/docs/config-deploy.rst @@ -0,0 +1,190 @@ +.. ===============LICENSE_START======================================================= +.. O-RAN SC CC-BY-4.0 +.. %% +.. Copyright (C) 2019 AT&T Intellectual Property and Nokia +.. %% +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. ===============LICENSE_END========================================================= + +RIC Dashboard Configuration and Deployment +========================================== + +This documents the configuration and deployment of the O-RAN SC RIC +Dashboard web application. + +Configuration +------------- + +The application requires the following configuration files. In the +usual Kubernetes deployment, all files are provided by a configuration +map:: + + application.properties + key.properties + portal.properties + + +Application Properties +^^^^^^^^^^^^^^^^^^^^^^ + +This Spring-Boot application reads key-value pairs from the file +``application.properties`` in the current working directory when +launched, or from the same file in a ``config`` subdirectory. Many +properties have default values cached within the application, in file +``src/main/resources/application.properties``. Properties with +default values do NOT need to be repeated in a deployment-specific +configuration. Properties without default values MUST be specified in +a 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. + +``anrxapp.url.prefix`` + +ANR Application URL prefix. No useful default. Usually a service name +like ``http://ricxapp-entry/anr`` + +``anrxapp.url.suffix`` + +ANR Application URL suffix. Default is the empty string. + +``appmgr.url.prefix`` + +Application Manager URL prefix. No useful default. Usually a service +name like ``http://ricplt-entry/appmgr`` + +``appmgr.url.suffix`` + +Application Manager URL suffix. Default is ``/ric/v1`` + +``e2mgr.url.prefix`` + +E2 Manager URL prefix. No useful default. Usually a service name like +``http://ricplt-entry/e2mgr`` + +``e2mgr.url.suffix`` + +E2 Manager URL prefix. Default is ``/v1`` + +``mock.config.delay`` + +Sleep period for mock methods in milliseconds. This mimics slow +endpoints. Default is ``0`` + +``portalapi.appname`` + +Application name expected at ONAP portal. Default is ``RIC Dashboard`` + +``portalapi.decryptor`` + +Java class that decrypts ciphertext from Portal. Default is +``org.oransc.ric.portal.dashboard.portalapi.PortalSdkDecryptorAes`` + +``portalapi.password`` + +Application password expected at ONAP portal. No default value. + +``portalapi.usercookie`` + +Name of request cookie with user ID. Default is ``UserId`` + +``portalapi.username`` + +Application user name expected at ONAP portal. No default value. + +``server.port`` + +Port where the Tomcat server listens for requests. Default is ``8080`` + +``userfile`` + +Path of file that stores user details. Default is ``users.json`` + + +Key Properties +^^^^^^^^^^^^^^ + +The file ``key.properties`` must be provided on the Java classpath for +the EPSDK-FW library. A sample file is in directory +``src/test/resources``. The file must contain the following entries, +listed here in alphabetical order. + +``cipher.enc.key`` + +Encryption key used by the EPSDK-FW library. No default value. + + +Portal Properties +^^^^^^^^^^^^^^^^^ + +The file ``portal.properties`` must be provided on the Java classpath +for the EPSDK-FW library. A sample file is in directory +``src/test/resources``. The file must contain the following entries, +listed here in alphabetical order. + +``ecomp_redirect_url`` + +URL of ONAP Portal. No default value. Usually a value like +``https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm`` + +``ecomp_rest_url`` + +URL of ONAP Portal REST endpoint. No default value. Usually a value +like ``http://portal-app.onap:8989/ONAPPORTAL/auxapi`` + +``portal.api.impl.class`` + +Java class name. No default value. Value must be +``org.oransc.ric.portal.dashboard.portalapi.PortalRestCentralServiceImpl`` + +``role_access_centralized`` + +Selector for role access. No default value. Value must be ``remote`` + +``ueb_app_key`` + +Unique key assigned by ONAP Portal to the RIC Dashboard application. +No default value. + + +Deployment +---------- + +A production server requires the configuration files listed above. +All files should be placed in a ``config`` directory. That name is important; +Spring automatically searches that directory for the ``application.properties`` +file. Further, that directory can easily be placed on the Java classpath so +the additional files can be found at runtime. + +After creating 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 \ + -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \ + org.springframework.boot.loader.PropertiesLauncher + +Alternately, to use the configuration in the "application-abc.properties" file, +modify the command to have "spring.config.name=name" like this:: + + java -cp config:target/ric-dash-be-1.2.0-SNAPSHOT.jar \ + -Dspring.config.name=application-abc \ + -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \ + org.springframework.boot.loader.PropertiesLauncher diff --git a/docs/config.rst b/docs/config.rst deleted file mode 100644 index 988543ca..00000000 --- a/docs/config.rst +++ /dev/null @@ -1,145 +0,0 @@ -.. ===============LICENSE_START======================================================= -.. O-RAN SC CC-BY-4.0 -.. %% -.. Copyright (C) 2019 AT&T Intellectual Property and Nokia -.. %% -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. ===============LICENSE_END========================================================= - -=========================== -RIC Dashboard Configuration -=========================== - -This documents the configuration parameters for the O-RAN SC RIC -Dashboard web application. - -Application Properties ----------------------- - -This Spring-Boot project reads parameters from file -``application.properties`` in the current working directory when -launched, or from the same file in a ``config`` subdirectory. The -application properties are listed in alphabetical order. Most have -default values, but not all. - -``a1med.url.prefix`` - -A1 Mediator URL prefix. Usually a service name like -"http://ricplt-entry/a1mediator" - -``a1med.url.suffix`` - -A1 Mediator URL suffix; default is empty. - -``anrxapp.url.prefix`` - -ANR Application URL prefix. Usually a service name like -"http://ricxapp-entry/anr" - -``anrxapp.url.suffix`` - -ANR Application URL suffix; default is empty. - -``appmgr.url.prefix`` - -Application Manager URL prefix. Usually a service name like -"http://ricplt-entry/appmgr" - -``appmgr.url.suffix`` - -Application Manager URL suffix. Default is "/ric/v1". - -``e2mgr.url.prefix`` - -E2 Manager URL prefix. Usually a service name like -"http://ricplt-entry/e2mgr". - -``e2mgr.url.suffix`` - -E2 Manager URL prefix. Default is "/v1". - -``mock.config.delay`` - -Sleep period for mock methods in milliseconds. This mimics slow -endpoints. Default is 0. - - -``portalapi.appname`` - -Application name expected at ONAP portal; default "RIC Dashboard" - -``portalapi.decryptor`` - -Java class that decrypts ciphertext from Portal; default -"org.oransc.ric.portal.dashboard.portalapi.PortalSdkDecryptorAes" - -``portalapi.password`` - -Application password expected at ONAP portal; no default. - -``portalapi.usercookie`` - -Name of request cookie with user ID; default "UserId" - -``portalapi.username`` - -Application user name expected at ONAP portal; no default. - -``server.port`` - -Tomcat server port, default 8080 - -``userfile`` - -Path to file that stores user details; default "users.json" - - -Key Properties --------------- - -The file ``key.properties`` must be found on the Java classpath. It -must contain the following entries. - -``cipher.enc.key`` - -Encryption key used by the EPSDK-FW library. - - -Portal Properties ------------------ - -The file ``portal.properties`` must be found on the Java classpath. -It must contain the following entries. - -``ecomp_redirect_url`` - -URL of ONAP Portal. Usually a value like -"https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm" - -``ecomp_rest_url`` - -URL of ONAP Portal REST endpoint. Usually a value like -"http://portal-app.onap:8989/ONAPPORTAL/auxapi" - -``portal.api.impl.class`` - -Java class name. Default is "org.oransc.ric.portal.dashboard.portalapi.PortalRestCentralServiceImpl" - -``role_access_centralized`` - -Default value is "remote". - -``ueb_app_key`` - -Unique key assigned by ONAP Portal to the RIC Dashboard application. -No default. diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst new file mode 100644 index 00000000..459360eb --- /dev/null +++ b/docs/developer-guide.rst @@ -0,0 +1,133 @@ +.. ===============LICENSE_START======================================================= +.. O-RAN SC CC-BY-4.0 +.. %% +.. Copyright (C) 2019 AT&T Intellectual Property and Nokia +.. %% +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. ===============LICENSE_END========================================================= + +RIC Dashboard Developer Guide +============================= + +This document provides a quickstart for developers of the O-RAN SC RIC Dashboard web application. + +Prerequisites +------------- + +1. Java development kit (JDK), version 11 or later +2. Maven dependency-management tool, version 3.4 or later + +Other tools including the Node Package Manager (npm) are fetched dynamically. + +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:: + + ./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: + + http://localhost:4200 + + +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: + + http://localhost:8080 + +The directory ``src/test/resources`` contains usable versions of the required property +files. These steps are required to launch: + +1. Set an environment variable via JVM argument: ``-Dorg.oransc.ric.portal.dashboard=mock`` +2. Run the JUnit test case ``DashboardServerTest`` which is not exactly a "test" because it never finishes. + +Both steps can be done with this command-line invocation:: + + mvn -Dorg.oransc.ric.portal.dashboard=mock -Dtest=DashboardTestServer test + +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:: + + 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. + +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 server authenticates requests using cookies that are set +by the ONAP Portal:: + + EPService + UserId + +The EPService value is not checked. The UserId value is decrypted +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:: + + Standard_User + System_Administrator + +Use the following structure in a JSON file to publish a user for the +user manager:: + + [ + { + "orgId":null, + "managerId":null, + "firstName":"Demo", + "middleInitial":null, + "lastName":"User", + "phone":null, + "email":null, + "hrid":null, + "orgUserId":null, + "orgCode":null, + "orgManagerUserId":null, + "jobTitle":null, + "loginId":"demo", + "active":true, + "roles":[ + { + "id":null, + "name":"Standard_User", + "roleFunctions":null + } + ] + } + ] diff --git a/docs/index.rst b/docs/index.rst index 470d1b66..bf1e1e9e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,7 +18,6 @@ .. RIC Dashboard documentation master -============= RIC Dashboard ============= @@ -28,7 +27,8 @@ RIC Dashboard :caption: Contents: overview.rst - config.rst + config-deploy.rst + developer-guide.rst release-notes.rst * :ref:`search` diff --git a/docs/overview.rst b/docs/overview.rst index 21029052..72de72fe 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -16,10 +16,83 @@ .. limitations under the License. .. ===============LICENSE_END========================================================= -====================== RIC Dashboard Overview ====================== -The O-RAN SC RIC Dashboard provides administrative and operator functions. -The web app is built as a single-page app using an Angular front end and a -Java Spring-Boot back end. +The O-RAN SC RIC Dashboard provides administrative and operator +functions for a radio access network (RAN) controller. The web app is +built as a single-page app using an Angular (version 8) front end and +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: + + ``_ + +Issues are tracked in the Linux Foundation Jira server: + + ``_ + +Project information is available in the Linux Foundation Wiki: + + ``_ + + +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. + + +Application Manager +------------------- + +The Dashboard interfaces with the Application Manager. This platform +component is accessed via HTTP/REST requests using a client that is +generated from an API specification published by the Application +Manager team. + +The Application Manager supports deploying, undeploying and +configuring applications in the RIC. The Dashboard UI provides screens +for these functions. + + +Automatic Neighbor Relation Application +--------------------------------------- + +The Dashboard interfaces with the Automatic Neighbor Relation (ANR) +application. This RIC application is accessed via HTTP/REST requests +using a client that is generated from an API specification published +by the ANR team. + +This RIC application discovers and manages the Neighbor Cell Relation +Table (NCRT). The Dashboard UI provides screens to view and modify +NCRT data. + + +E2 Manager +---------- + +The Dashboard interfaces with the E2 Manager. This platform +component is accessed via HTTP/REST requests using a client that is +generated from an API specification published by the E2 Manager team. + +The E2 Manager platform component supports connecting and +disconnecting RAN elements. The Dashboard UI provides controls for +operators to create "ENDC" and "X2" connections, and to disconnect RAN +elements. diff --git a/docs/release-notes.rst b/docs/release-notes.rst index 6ab767da..a66d5d49 100644 --- a/docs/release-notes.rst +++ b/docs/release-notes.rst @@ -16,7 +16,6 @@ .. limitations under the License. .. ===============LICENSE_END========================================================= -=========================== RIC Dashboard Release Notes =========================== diff --git a/webapp-backend/README.md b/webapp-backend/README.md index 67e4a3b6..48c93805 100644 --- a/webapp-backend/README.md +++ b/webapp-backend/README.md @@ -2,130 +2,12 @@ The RIC Dashboard back-end provides REST services to the Dashboard front-end Typescript features running in the user's browser. For -production use, this server also offers the Angular application files. +production use, it also serves the Angular application files. -The server uses the ONAP Portal's "EPSDK-FW" library to support -single-sign-on (SSO) feature, which requires users to authenticate -at the ONAP Portal UI. Authentication features including SSO are -excluded by Spring profiles when running the back-end as a development -server, see below. +Please see the documentation in the docs/ folder. -## Launch production server - -This server requires several configuration files: - - application.properties - read from filesystem - key.properties - read from Java classpath - portal.properties - read from Java classpath - -All files should be placed in a "config" directory. That name is important; -Spring automatically searches that directory for the application.properties file. -Further, that directory is placed on the Java classpath so the additional -files can be read at runtime. - -These steps are required: - -1. Check the set of properties files in the config folder, and create - files from templates as needed. E.g., copy - "key.properties.template" to "key.properties". -2. Add the config folder to the Java classpath -3a. Launch the server with this command-line invocation that includes the - config directory on the Java classpath: - - java -cp config:target/ric-dash-be-1.2.0-SNAPSHOT.jar \ - -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \ - org.springframework.boot.loader.PropertiesLauncher - -3b. Alternately, to use the configuration in the "application-abc.properties" file, -add a key-value pair for "spring.config.name" and launch with this invocation: - - java -cp config:target/ric-dash-be-1.2.0-SNAPSHOT.jar \ - -Dspring.config.name=application-abc \ - -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \ - org.springframework.boot.loader.PropertiesLauncher - -### Production user authentication - -TODO AUTH: Authentication temporarily disabled for Sprint 2 testing! - -The regular server authenticates requests using cookies that are set -by the ONAP Portal: - - EPService - UserId - -The EPService value is not checked. The UserId value is decrypted -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 DashboardConstants class. -A standard user can read (GET) all methods but not make changes. -An administrator can read (GET) and write (POST PUT DELETE) all data. - - Standard_User - System_Administrator - -Use the following structure in a JSON file to publish a user for the -user manager: - - [ - { - "orgId":null, - "managerId":null, - "firstName":"Demo", - "middleInitial":null, - "lastName":"User", - "phone":null, - "email":null, - "hrid":null, - "orgUserId":null, - "orgCode":null, - "orgManagerUserId":null, - "jobTitle":null, - "loginId":"demo", - "active":true, - "roles":[ - { - "id":null, - "name":"Standard_User", - "roleFunctions":null - } - ] - } - ] - - -## Launch development server - -The development server uses local configuration and serves mock data -that simulates the behavior of remote endpoints. The directory -src/main/resources contains usable versions of the required property -files. These steps are required to launch: - -1. Set an environment variable via JVM argument: "-Dorg.oransc.ric.portal.dashboard=mock" -2. Run the JUnit test case DashboardServerTest -- not exactly a "test" because it never finishes. - -Both steps can be done with this command-line invocation: - - mvn -Dorg.oransc.ric.portal.dashboard=mock -Dtest=DashboardTestServer test - -### 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 credentials are 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 defined -in the class shown above. - -## Swagger API documentation - -Both a regular and a development server publish API documentation at URL `http://localhost:8080/swagger-ui.html`. +The backend server publishes live API documentation at the +URL `http://your-host-name-here:8080/swagger-ui.html` ## License