Add overview of supported components and applications.
Move README.md content to developer's guide.
Change-Id: I8bcd519c041a73a645007ac289d771e92be29c43
Signed-off-by: Lott, Christopher (cl778h) <cl778h@att.com>
# 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
--- /dev/null
+.. ===============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
+++ /dev/null
-.. ===============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.
--- /dev/null
+.. ===============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
+ }
+ ]
+ }
+ ]
.. RIC Dashboard documentation master
-=============
RIC Dashboard
=============
:caption: Contents:
overview.rst
- config.rst
+ config-deploy.rst
+ developer-guide.rst
release-notes.rst
* :ref:`search`
.. 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:
+
+ `<https://gerrit.o-ran-sc.org/r/portal/ric-dashboard;a=summary>`_
+
+The build (CI) jobs are in the Linux Foundation Jenkins server:
+
+ `<https://jenkins.o-ran-sc.org/view/portal-ric-dashboard>`_
+
+Issues are tracked in the Linux Foundation Jira server:
+
+ `<https://jira.o-ran-sc.org/secure/Dashboard.jspa>`_
+
+Project information is available in the Linux Foundation Wiki:
+
+ `<https://wiki.o-ran-sc.org>`_
+
+
+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.
.. limitations under the License.
.. ===============LICENSE_END=========================================================
-===========================
RIC Dashboard Release Notes
===========================
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
Code Review / portal / ric-dashboard.git / commitdiff