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