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. Install all project jar files locally
  59 2. Set an environment variable via JVM argument: ``-Dorg.oransc.ric.portal.dashboard=mock``
  60 3. Run the JUnit test case ``DashboardServerTest`` which is not exactly a "test" because it never finishes.
  61
  62 These steps can be done with these commands::
  63
  64      mvn -Ddocker.skip=true -DskipTests=true install
  65      mvn -Dorg.oransc.ric.portal.dashboard=mock -Dtest=DashboardTestServer test
  66
  67 Development user authentication
  68 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  69
  70 The development server requires basic HTTP user authentication for all requests. Like
  71 the production server, it requires HTTP headers with authentication for Portal API
  72 requests.  The username and password are stored in constants in this Java class in
  73 the ``src/test/java`` folder::
  74
  75     org.oransc.ric.portal.dashboard.config.WebSecurityMockConfiguration
  76
  77 Like the production server, the development server also performs role-based
  78 authentication on requests. The user name-role name associations are also defined
  79 in the class shown above.
  80
  81 Production user authentication
  82 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  83
  84 The server uses the ONAP Portal's "EPSDK-FW" library to support a
  85 single-sign-on (SSO) feature, which requires users to authenticate
  86 at the ONAP Portal UI. The RIC Dashboard can be on-boarded as an
  87 application on the ONAP Portal using its application on-boarding UI.
  88
  89 The server authenticates requests using cookies that are set
  90 by the ONAP Portal::
  91
  92      EPService
  93      UserId
  94
  95 The EPService value is not checked.  The UserId value is decrypted
  96 using a secret key shared with the ONAP Portal to yield a user ID.
  97 That ID must match a user's loginId defined in the user manager.
  98
  99 The regular server checks requests for the following granted
 100 authorities (role names), as defined in the java class ``DashboardConstants``.
 101 A standard user can invoke all "GET" methods but not make changes.
 102 A system administrator can invoke all methods ("GET", "POST", "PUT",
 103 "DELETE") to make arbitrary changes::
 104
 105     Standard_User
 106     System_Administrator
 107
 108 Use the following structure in a JSON file to publish a user for the
 109 user manager::
 110
 111     [
 112      {
 113       "orgId":null,
 114       "managerId":null,
 115       "firstName":"Demo",
 116       "middleInitial":null,
 117       "lastName":"User",
 118       "phone":null,
 119       "email":null,
 120       "hrid":null,
 121       "orgUserId":null,
 122       "orgCode":null,
 123       "orgManagerUserId":null,
 124       "jobTitle":null,
 125       "loginId":"demo",
 126       "active":true,
 127       "roles":[
 128          {
 129             "id":null,
 130             "name":"Standard_User",
 131             "roleFunctions":null
 132          }
 133       ]
 134      }
 135     ]