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 ``userfile``
 117
 118 Path of file that stores user details. Default is ``users.json``
 119
 120
 121 Key Properties
 122 ^^^^^^^^^^^^^^
 123
 124 The file ``key.properties`` must be provided on the Java classpath for
 125 the EPSDK-FW library.  A sample file is in directory
 126 ``src/test/resources``.  The file must contain the following entries,
 127 listed here in alphabetical order.
 128
 129 ``cipher.enc.key``
 130
 131 Encryption key used by the EPSDK-FW library.  No default value.
 132
 133
 134 Portal Properties
 135 ^^^^^^^^^^^^^^^^^
 136
 137 The file ``portal.properties`` must be provided on the Java classpath
 138 for the EPSDK-FW library.  A sample file is in directory
 139 ``src/test/resources``.  The file must contain the following entries,
 140 listed here in alphabetical order.
 141
 142 ``ecomp_redirect_url``
 143
 144 URL of ONAP Portal.  No default value. Usually a value like
 145 ``https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm``
 146
 147 ``ecomp_rest_url``
 148
 149 URL of ONAP Portal REST endpoint.  No default value.  Usually a value
 150 like ``http://portal-app.onap:8989/ONAPPORTAL/auxapi``
 151
 152 ``portal.api.impl.class``
 153
 154 Java class name.  No default value.  Value must be
 155 ``org.oransc.ric.portal.dashboard.portalapi.PortalRestCentralServiceImpl``
 156
 157 ``role_access_centralized``
 158
 159 Selector for role access.  No default value.  Value must be ``remote``
 160
 161 ``ueb_app_key``
 162
 163 Unique key assigned by ONAP Portal to the RIC Dashboard application.
 164 No default value.
 165
 166
 167 Deployment
 168 ----------
 169
 170 A production server requires the configuration files listed above.
 171 All files should be placed in a ``config`` directory.  That name is important;
 172 Spring automatically searches that directory for the ``application.properties``
 173 file. Further, that directory can easily be placed on the Java classpath so
 174 the additional files can be found at runtime.
 175
 176 After creating and mounting Kubernetes config maps appropriately, launch
 177 the server with this command-line invocation to include the ``config`` directory
 178 on the Java classpath::
 179
 180     java -cp config:target/ric-dash-be-1.2.0-SNAPSHOT.jar \
 181         -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \
 182         org.springframework.boot.loader.PropertiesLauncher
 183
 184 Alternately, to use the configuration in the "application-abc.properties" file,
 185 modify the command to have "spring.config.name=name" like this::
 186
 187     java -cp config:target/ric-dash-be-1.2.0-SNAPSHOT.jar \
 188         -Dspring.config.name=application-abc \
 189         -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \
 190         org.springframework.boot.loader.PropertiesLauncher