docs/developer-guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3
   4 RIC Dashboard Developer Guide
   5 =============================
   6
   7 This document provides a quickstart for developers of the O-RAN SC RIC Dashboard web
   8 application.
   9
  10 Prerequisites
  11 -------------
  12
  13 1. Java development kit (JDK), version 11 or later
  14 2. Maven dependency-management tool, version 3.4 or later
  15
  16 Other required tools including the Node Package Manager (npm) are fetched dynamically.
  17
  18 Clone and Update Submodules
  19 ---------------------------
  20
  21 After cloning the repository, initialize and update all git submodules like this::
  22
  23     git submodule init
  24     git submodule update
  25
  26 Check the submodule status at any time like this::
  27
  28     git submodule status
  29
  30
  31 Angular Front-End Application
  32 -----------------------------
  33
  34 The Angular 8 application files are in subdirectory ``webapp-frontend``.
  35 Build the front-end application via ``mvn package``.  For development and debugging,
  36 build the application, then launch an ng development server using this command::
  37
  38     ./ng serve --proxy-config proxy.conf.json
  39
  40 The app will automatically reload in the browser if you change any of the source files.
  41 The ng server listens for requests at this URL:
  42
  43     http://localhost:4200
  44
  45
  46 Spring-Boot Back-End Application
  47 --------------------------------
  48
  49 A development (not production) server uses local configuration and serves mock data
  50 that simulates the behavior of remote endpoints.  The back-end server listens for
  51 requests at this URL:
  52
  53     http://localhost:8080
  54
  55 The directory ``src/test/resources`` contains usable versions of the required property
  56 files.  These steps are required to launch:
  57
  58 1. Set an environment variable via JVM argument: ``-Dorg.oransc.ric.portal.dashboard=mock``
  59 2. Run the JUnit test case ``DashboardServerTest`` which is not exactly a "test" because it never finishes.
  60
  61 Both steps can be done with this command-line invocation::
  62
  63      mvn -Dorg.oransc.ric.portal.dashboard=mock -Dtest=DashboardTestServer test
  64
  65 Development user authentication
  66 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  67
  68 The development server requires basic HTTP user authentication for all requests. Like
  69 the production server, it requires HTTP headers with authentication for Portal API
  70 requests.  The username and password are stored in constants in this Java class in
  71 the ``src/test/java`` folder::
  72
  73     org.oransc.ric.portal.dashboard.config.WebSecurityMockConfiguration
  74
  75 Like the production server, the development server also performs role-based
  76 authentication on requests. The user name-role name associations are also defined
  77 in the class shown above.
  78
  79 Production user authentication
  80 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  81
  82 The server uses the ONAP Portal's "EPSDK-FW" library to support a
  83 single-sign-on (SSO) feature, which requires users to authenticate
  84 at the ONAP Portal UI. The RIC Dashboard can be on-boarded as an
  85 application on the ONAP Portal using its application on-boarding UI.
  86
  87 The server authenticates requests using cookies that are set
  88 by the ONAP Portal::
  89
  90      EPService
  91      UserId
  92
  93 The EPService value is not checked.  The UserId value is decrypted
  94 using a secret key shared with the ONAP Portal to yield a user ID.
  95 That ID must match a user's loginId defined in the user manager.
  96
  97 The regular server checks requests for the following granted
  98 authorities (role names), as defined in the java class ``DashboardConstants``.
  99 A standard user can invoke all "GET" methods but not make changes.
 100 A system administrator can invoke all methods ("GET", "POST", "PUT",
 101 "DELETE") to make arbitrary changes::
 102
 103     Standard_User
 104     System_Administrator
 105
 106 Use the following structure in a JSON file to publish a user for the
 107 user manager::
 108
 109     [
 110      {
 111       "orgId":null,
 112       "managerId":null,
 113       "firstName":"Demo",
 114       "middleInitial":null,
 115       "lastName":"User",
 116       "phone":null,
 117       "email":null,
 118       "hrid":null,
 119       "orgUserId":null,
 120       "orgCode":null,
 121       "orgManagerUserId":null,
 122       "jobTitle":null,
 123       "loginId":"demo",
 124       "active":true,
 125       "roles":[
 126          {
 127             "id":null,
 128             "name":"Standard_User",
 129             "roleFunctions":null
 130          }
 131       ]
 132      }
 133     ]