Add RST documentation

[portal/ric-dashboard.git] / docs / developer-guide.rst

diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst
new file mode 100644 (file)
index 0000000..459360e
--- /dev/null
+++ b/docs/developer-guide.rst
@@ -0,0 +1,133 @@
+.. ===============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
+         }
+      ]
+     }
+    ]