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