docs/developer-guide.rst

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