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.
  24
  25 Configuration
  26 -------------
  27
  28 The application requires the following configuration files.  In the
  29 usual Kubernetes deployment, all files are provided by a configuration
  30 map::
  31
  32     application.properties
  33     key.properties
  34     portal.properties
  35
  36
  37 Application Properties
  38 ^^^^^^^^^^^^^^^^^^^^^^
  39
  40 This Spring-Boot application reads key-value pairs from the file
  41 ``application.properties`` in the current working directory when
  42 launched, or from the same file in a ``config`` subdirectory.  Many
  43 properties have default values cached within the application, in file
  44 ``src/main/resources/application.properties``.  Properties with
  45 default values do NOT need to be repeated in a deployment-specific
  46 configuration.  Properties without default values MUST be specified in
  47 a deployment-specific configuration. The properties are listed below
  48 in alphabetical order.
  49
  50 ``a1med.url.prefix``
  51
  52 A1 Mediator URL prefix.  No useful default. Usually a service name
  53 like ``http://ricplt-entry/a1mediator``
  54
  55 ``a1med.url.suffix``
  56
  57 A1 Mediator URL suffix. Default is the empty string.
  58
  59 ``anrxapp.url.prefix``
  60
  61 ANR Application URL prefix.  No useful default. Usually a service name
  62 like ``http://ricxapp-entry/anr``
  63
  64 ``anrxapp.url.suffix``
  65
  66 ANR Application URL suffix. Default is the empty string.
  67
  68 ``appmgr.url.prefix``
  69
  70 Application Manager URL prefix. No useful default. Usually a service
  71 name like ``http://ricplt-entry/appmgr``
  72
  73 ``appmgr.url.suffix``
  74
  75 Application Manager URL suffix. Default is ``/ric/v1``
  76
  77 ``e2mgr.url.prefix``
  78
  79 E2 Manager URL prefix. No useful default. Usually a service name like
  80 ``http://ricplt-entry/e2mgr``
  81
  82 ``e2mgr.url.suffix``
  83
  84 E2 Manager URL prefix. Default is ``/v1``
  85
  86 ``mock.config.delay``
  87
  88 Sleep period for mock methods in milliseconds.  This mimics slow
  89 endpoints. Default is ``0``
  90
  91 ``portalapi.appname``
  92
  93 Application name expected at ONAP portal. Default is ``RIC Dashboard``
  94
  95 ``portalapi.decryptor``
  96
  97 Java class that decrypts ciphertext from Portal. Default is
  98 ``org.oransc.ric.portal.dashboard.portalapi.PortalSdkDecryptorAes``
  99
 100 ``portalapi.password``
 101
 102 Application password expected at ONAP portal. No default value.
 103
 104 ``portalapi.usercookie``
 105
 106 Name of request cookie with user ID. Default is ``UserId``
 107
 108 ``portalapi.username``
 109
 110 Application user name expected at ONAP portal. No default value.
 111
 112 ``server.port``
 113
 114 Port where the Tomcat server listens for requests. Default is ``8080``
 115
 116 ``metrics.url.ac``
 117
 118 Url to the kibana source which visualizes AC App metrics. No default value and needs to be replaced with actual value during deployment time.
 119
 120 ``userfile``
 121
 122 Path of file that stores user details. Default is ``users.json``
 123
 124
 125 Key Properties
 126 ^^^^^^^^^^^^^^
 127
 128 The file ``key.properties`` must be provided on the Java classpath for
 129 the EPSDK-FW library.  A sample file is in directory
 130 ``src/test/resources``.  The file must contain the following entries,
 131 listed here in alphabetical order.
 132
 133 ``cipher.enc.key``
 134
 135 Encryption key used by the EPSDK-FW library.  No default value.
 136
 137
 138 Portal Properties
 139 ^^^^^^^^^^^^^^^^^
 140
 141 The file ``portal.properties`` must be provided on the Java classpath
 142 for the EPSDK-FW library.  A sample file is in directory
 143 ``src/test/resources``.  The file must contain the following entries,
 144 listed here in alphabetical order.
 145
 146 ``ecomp_redirect_url``
 147
 148 URL of ONAP Portal.  No default value. Usually a value like
 149 ``https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm``
 150
 151 ``ecomp_rest_url``
 152
 153 URL of ONAP Portal REST endpoint.  No default value.  Usually a value
 154 like ``http://portal-app.onap:8989/ONAPPORTAL/auxapi``
 155
 156 ``portal.api.impl.class``
 157
 158 Java class name.  No default value.  Value must be
 159 ``org.oransc.ric.portal.dashboard.portalapi.PortalRestCentralServiceImpl``
 160
 161 ``role_access_centralized``
 162
 163 Selector for role access.  No default value.  Value must be ``remote``
 164
 165 ``ueb_app_key``
 166
 167 Unique key assigned by ONAP Portal to the RIC Dashboard application.
 168 No default value.
 169
 170
 171 Deployment
 172 ----------
 173
 174 A production server requires the configuration files listed above.
 175 All files should be placed in a ``config`` directory.  That name is important;
 176 Spring automatically searches that directory for the ``application.properties``
 177 file. Further, that directory can easily be placed on the Java classpath so
 178 the additional files can be found at runtime.
 179
 180 After creating and mounting Kubernetes config maps appropriately, launch
 181 the server with this command-line invocation to include the ``config`` directory
 182 on the Java classpath::
 183
 184     java -cp config:target/ric-dash-be-1.2.0-SNAPSHOT.jar \
 185         -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \
 186         org.springframework.boot.loader.PropertiesLauncher
 187
 188 Alternately, to use the configuration in the "application-abc.properties" file,
 189 modify the command to have "spring.config.name=name" like this::
 190
 191     java -cp config:target/ric-dash-be-1.2.0-SNAPSHOT.jar \
 192         -Dspring.config.name=application-abc \
 193         -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \
 194         org.springframework.boot.loader.PropertiesLauncher