docs/config-deploy.rst

   1 .. ===============LICENSE_START=======================================================
   2 .. O-RAN SC CC-BY-4.0
   3 .. %%
   4 .. Copyright (C) 2019 AT&T Intellectual Property and Nokia
   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 Configuration and Deployment
  20 ==========================================
  21
  22 This documents the configuration and deployment of the O-RAN SC RIC
  23 Dashboard web application, which is often deployed together with the
  24 ONAP Portal.
  25
  26 Configuration
  27 -------------
  28
  29 The application requires the following configuration files::
  30
  31     application.properties
  32     key.properties
  33     portal.properties
  34
  35 In the usual Kubernetes deployment, all file contents are provided by
  36 a configuration map.
  37
  38 Application Properties
  39 ^^^^^^^^^^^^^^^^^^^^^^
  40
  41 The file ``application.properties`` must be provided when the
  42 application is launched, either in the current working directory or in
  43 a ``config`` subdirectory (latter is preferred). The Helm chart that
  44 deploys the application should mount this file appropriately.
  45
  46 Many properties have default values cached within the application, in
  47 file ``src/main/resources/application.properties``.  Properties with
  48 default values do NOT need to be repeated in a deployment-specific
  49 configuration.  Properties without default values MUST be specified in
  50 a deployment-specific configuration.
  51
  52 The properties are listed below in alphabetical order.
  53
  54 ``a1med.url.prefix``
  55
  56 A1 Mediator URL prefix.  No useful default. Usually a service name
  57 like ``http://ricplt-entry/a1mediator``
  58
  59 ``a1med.url.suffix``
  60
  61 A1 Mediator URL suffix. Default is the empty string.
  62
  63 ``anrxapp.url.prefix``
  64
  65 ANR Application URL prefix.  No useful default. Usually a service name
  66 like ``http://ricxapp-entry/anr``
  67
  68 ``anrxapp.url.suffix``
  69
  70 ANR Application URL suffix. Default is the empty string.
  71
  72 ``appmgr.url.prefix``
  73
  74 Application Manager URL prefix. No useful default. Usually a service
  75 name like ``http://ricplt-entry/appmgr``
  76
  77 ``appmgr.url.suffix``
  78
  79 Application Manager URL suffix. Default is ``/ric/v1``
  80
  81 ``e2mgr.url.prefix``
  82
  83 E2 Manager URL prefix. No useful default. Usually a service name like
  84 ``http://ricplt-entry/e2mgr``
  85
  86 ``e2mgr.url.suffix``
  87
  88 E2 Manager URL prefix. Default is ``/v1``
  89
  90 ``mock.config.delay``
  91
  92 Sleep period for mock methods in milliseconds.  This mimics slow
  93 endpoints. Default is ``0``
  94
  95 ``portalapi.appname``
  96
  97 Application name expected at ONAP portal. Default is ``RIC Dashboard``
  98
  99 ``portalapi.decryptor``
 100
 101 Java class that decrypts ciphertext from Portal. Default is
 102 ``org.oransc.ric.portal.dashboard.portalapi.PortalSdkDecryptorAes``
 103
 104 ``portalapi.password``
 105
 106 REST password expected at ONAP portal. No default value.
 107
 108 ``portalapi.security``
 109
 110 Boolean flag whether the Dashboard limits access to users (browsers)
 111 that present security tokens set by the ONAP Portal.  If false, no
 112 access control is performed, which is only appropriate for isolated
 113 lab testing.
 114
 115 ``portalapi.usercookie``
 116
 117 Name of request cookie with user ID. Default is ``UserId``
 118
 119 ``portalapi.username``
 120
 121 REST user name expected at ONAP portal. No default value.
 122
 123 ``server.port``
 124
 125 Port where the Tomcat server listens for requests. Default is ``8080``
 126
 127 ``metrics.url.ac``
 128
 129 Url to the kibana source which visualizes AC App metrics. No default value and needs to be replaced with actual value during deployment time.
 130
 131 ``userfile``
 132
 133 Path of file that stores user details. Default is ``users.json``
 134
 135
 136 Key Properties
 137 ^^^^^^^^^^^^^^
 138
 139 The file ``key.properties`` must be provided on the Java classpath for
 140 the Spring-Boot application, as required by the EPSDK-FW library. The
 141 Helm chart for the application should mount this file appropriately.
 142 A sample file is in directory ``src/test/resources``.
 143
 144 The file must contain the following entries, listed here in
 145 alphabetical order.
 146
 147 ``cipher.enc.key``
 148
 149 Encryption key used by the EPSDK-FW library.  No default value.
 150
 151
 152 Portal Properties
 153 ^^^^^^^^^^^^^^^^^
 154
 155 The file ``portal.properties`` must be provided on the Java classpath
 156 for the application, as required by the EPSDK-FW library.  The Helm
 157 chart for the application should mount this file appropriately.  A
 158 sample file is in directory ``src/test/resources``.
 159
 160 The file must contain the following entries, listed here in
 161 alphabetical order.
 162
 163 ``ecomp_redirect_url``
 164
 165 Portal URL that is reachable by a user's browser.  This is a value
 166 like
 167 ``https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm``
 168
 169 ``ecomp_rest_url``
 170
 171 Portal REST URL that is reachable by the Dashboard back-end.
 172 This is a value like ``http://portal-app.onap:8989/ONAPPORTAL/auxapi``
 173
 174 ``portal.api.impl.class``
 175
 176 Java class name.  No default value.  Value must be
 177 ``org.oransc.ric.portal.dashboard.portalapi.PortalRestCentralServiceImpl``
 178
 179 ``role_access_centralized``
 180
 181 Selector for role access.  No default value.  Value must be ``remote``
 182
 183 ``ueb_app_key``
 184
 185 Unique key assigned by ONAP Portal to the RIC Dashboard application.
 186 No default value.
 187
 188
 189 Deployment
 190 ----------
 191
 192 A production server requires the configuration files listed above.
 193 All files should be placed in a ``config`` directory.  That name is
 194 important; Spring automatically searches that directory for the
 195 ``application.properties`` file. Further, that directory can easily be
 196 placed on the Java classpath so the additional files can be found at
 197 runtime.
 198
 199
 200 On-Board Dashboard to ONAP Portal
 201 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 202
 203 When on-boarding the Dashboard to the ONAP Portal the administrator
 204 must supply the following information about the deployed instance:
 205
 206 - Dashboard URL that is reachable by a user's browser. The domain of
 207   this host name must match the Portal URL that is similarly reachable
 208   by a user's browser for cookie-based authentication to function as
 209   expected.  This should be a value like
 210   ``http://dashboard.simpledemo.onap.org:8080``
 211 - Dashboard REST URL that is reachable by the Portal back-end server.
 212   This can be a host name or an IP address, because it does not use
 213   cookie-based authentication.  This must be a URL with suffix "/api/v3"
 214   for example ``http://192.168.1.1:8080/api/v3``.
 215
 216 The Dashboard server only listens on a single port, so the examples
 217 above both use the same port number.  Different port numbers might be
 218 required if an ingress controller or other proxy server is used.
 219
 220 After the on-boarding process is complete, the administrator must
 221 enter values from the Portal for the following properties explained
 222 above:
 223
 224 - ``portalapi.password``
 225 - ``portalapi.username``
 226 - ``ueb_app_key``
 227
 228 Launch Server
 229 ^^^^^^^^^^^^^
 230
 231 After creating, populating and mounting Kubernetes config maps
 232 appropriately, launch the server with this command-line invocation to
 233 include the ``config`` directory on the Java classpath::
 234
 235     java -cp config:target/ric-dash-be-1.2.0-SNAPSHOT.jar \
 236         -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \
 237         org.springframework.boot.loader.PropertiesLauncher
 238
 239 Alternately, to use the configuration in the "application-abc.properties" file,
 240 modify the command to have "spring.config.name=name" like this::
 241
 242     java -cp config:target/ric-dash-be-1.2.0-SNAPSHOT.jar \
 243         -Dspring.config.name=application-abc \
 244         -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \
 245         org.springframework.boot.loader.PropertiesLauncher