path: root/dcae_dmaapbc_webapp/dbc-app-deployment-guide.txt

	DEPLOYMENT AND ON-BOARDING GUIDE 
	for the
	DATA BUS CONTROLLER WEB APPLICATION

	ECOMP Release 1610

	
	Contact: Christopher Lott

--

1.0 Purpose and Scope

1.1 This deployment guide offers instructions to install the Data Bus
Controller webapp in ECOMP Release 1610, and to on-board the application
into the ECOMP Portal.

This application is packaged as a single WAR file with all CSS, HTML, 
JavaScript, compiled Java classes and Jar files together in a single 
deployable bundle.  No front-end/back-end separation is implemented for 
1610.

2.0 Service Impact and Time Estimates

2.1 This DG has the following estimated timings and service impacts:
 
Name				Estimated Time		Service Impact
----				------------		-----------
Pre Maintenance		N/A					N/A
Window

Maintenance			60					App is down
Window

Post Maintenance	N/A					N/A
Window

Rollback			30					App is down
Procedure


3.0 Assumptions

3.1 The operator who is performing the change must have adequate
system administrative privileges for the affected systems, which usually
means superuser access on the Linux host, and Portal administrator
status in the ECOMP Portal.

3.2 This deployment guide assumes that ECOMP Portal 1610 is installed
and working according to that release’s Deployment Guide. 

3.3 Nick Picciocca will be the DevOps escalation for this change.
    
3.4 For staged files, ENV will represent the overall environment and
SERVERNAME is a file specific to the server.

3.4.1 Valid environments in 1610 are as follows:
      DEVN1
      QA1
      QA2
      IST (not geo redundant)
      ETE1
      ETE2
      PROD1
      PROD2

4.0 Prerequisites

4.1 All connectivity should be in place and tested.

4.1.1 Please see ECP_CM_v2.2.xlsx (connectivity matrix).

4.1.2 WebJunction addresses have been created for the DMaaP Bus Control
application, using the usual CSP-WJ application form.
Although the application is co-hosted with the Portal application, sharing
the Portal's WJ is not sufficient - proper cookie management requires two 
separate WJ addresses.  Addresses are defined for the DEV_N1, QA, IST, ETE
and PROD environments.

4.2 All tooling must properly installed to support UAM / SWM based installation.

4.3 Software

4.3.1 Java

Java version 1.8 with a recent update must be installed.  Java includes a
file with known root certificates, which may require changes to recognize
self-signed server certificates. 

4.3.2 Apache Tomcat

Version 8 of the Apache Tomcat server must be installed.  The Apache HTTPD
package may also be required, but details about front-end (HTTPD) / back-end
(Tomcat) separation are outside the scope of this document.

4.3.3 MariaDB

These instructions assume version 10.1.13-MariaDB or later.

4.4 Web Application Archive (WAR) File

The DBC web application is built by maven and packaged as a war file.  This
deployment guide does not cover the build process, which is assumed to be
covered by Continuous Integration / Continuous Deployment efforts.

4.5 Property Files

The DBC web app requires appropriate configuration for each deployment environment.
Configurations are represented as key-values pairs stored in property files. 
	
4.5.1 Portal Properties for ecompFW Library

This file within the web application contains properties used by the ecompFW library:

	WEB-INF/classes/portal.properties

The application requires the location of the hosting Portal's REST endpoint in
this config key:
	- ecomp_rest_url

The application requires the unique UEB key that's assigned during the on-boarding
process in the following config key:
	- ueb_app_key


4.5.2 Quantum Library System Properties

This file within the web application database properties used by the ecompSDK-core library:

	WEB-INF/conf/system.properties

The application requires the base URL of the WebJunction where users enter via 
the Portal application, which is a proper prefix of the URL used to on-board the 
application to Portal.  The file in source code management has the expected values 
for each environment in release 1610 for use in the following key:
	- app_base_url

The application requires suitable database coordinates in the following config keys.
Note that the database password must be encrypted using the ECOMP Portal utility class
CipherUtil:
	- db.connectionURL
	- db.userName
	- db.password

For example, the following connection URL configures the application for a local MySQL
database named "dbca":

	db.connectionURL = jdbc:mysql://localhost:3306/dbca

As part of deployment, the following config key must be updated with a unique UUID.  
For example, a new value can be generated at https://www.uuidgenerator.net/version1
	- instance_uuid


4.5.3 Data Bus Control App Properties

This file within the web application properties used by the web application;
an example file is in source code management:

	WEB-INF/dbcapp/dbcapp.properties

The application requires a comma-separated list of DCAE DMaaP Bus Controller 
URLs in the following config key. The file in source code management has the 
expected values for each environment in release 1610 for use in the following key:
	- dmaap.rest.url.list

As part of deployment, the following key must be set to choose whether the DMaaP 
access profile interface is a local database ("dao") or the micro service ("rest").
In release 1610 the expected value is "rest"; the other is only for debugging.
	- profile.access.method
	
If the profile access method  is "rest" (i.e., microservice), the following keys must be 
configured with the coordinates of the micro service.  The URL will always use "localhost" 
as the hostname, but the port may vary: 
	- profile.microservice.url
	- profile.microservice.user.name
	- profile.microservice.user.password

Finally, the application uses a mech ID as the default credentials presented to the 
DCAE REST endpoint.  A mech ID and password must be configured using the following keys.
The file in source code management has the mech ID assigned to the web application, and
the password is encrypted using the ECOMP Portal utility class CipherUtil.  No changes 
are expected to these config keys during deployment:
	- dmaap.mechid.name
	- dmaap.mechid.password

	
PRE MAINTENANCE WINDOW PREPARATION

    N/A
 

MAINTENANCE WINDOW WORK (60 mins)

5.0 Database

This uses MariaDB.
 
5.1 Database Creation

Login to the database with super user privileges and type the following commands
to create a Mysql database, create a user and grant privileges to the user to 
access all tables in the new database:  

% mysql -u root -p

	create database dbca;
	create user 'dbcuser'@'localhost' identified by 'dbpa1234';
	grant all on dbca.* to dbcuser@localhost;

5.2 Database Loading

As part of deployment the database must be loaded with menu items and a super user entry.
The following files are part of the application source area. Copy these files to /var/tmp:

	db-scripts/EcompSdkDDLMySql.sql
	db-scripts/EcompSdkDMLMySql.sql
	db-scripts/dbca-ddl-dml-mysql.sql

Create tables and populate the tables by running the scripts in the order shown below.  
On one node of the MariaDB Cluster, in the Mysql command-line client, execute the following 
commands:

	source /var/tmp/EcompSdkDDLMySql.sql
	source /var/tmp/EcompSdkDMLMySql.sql
	source /var/tmp/dbca-ddl-dml-mysql.sql


6.0 Application Installation

6.1 Copy the application war file and the property files as prepared above to directory /var/tmp:

	dmaap-bc-app-1.0.war
	portal.properties-1610
	system.properties-1610

6.2 Deploy the application war file. 

Stop the server and clean the logs

   service tomcat stop
   rm -f /opt/app/tomcat/logs/catalina.out

If a previous version is installed, make a backup:

Copy the war file to the server's webapps area (the destination names are suggestions only):

Start the server so it unpacks the WAR archive, then immediately stop the server again. 
  service tomcat start; sleep 30; service tomcat stop
  
Copy the appropriate property files into place:

  cp /var/tmp/system.properties-1610 /opt/app/tomcat/webapps/dmaap-bc-app/WEB-INF/conf/system.properties
  cp /var/tmp/portal.properties-1610 /opt/app/tomcat/webapps/dmaap-bc-app/WEB-INF/classes/portal.properties


6.3 Test Tomcat and Application:

Launch the Tomcat server. It should deploy the application.  After starting, verify there are no 
relevant errors in file /opt/app/tomcat/logs/application.log

  service tomcat start
  service tomcat status
  tail -f /opt/app/tomcat/logs/catalina.out 

6.4 Login to Application

After the database is first created the application has exactly one user, and that user has
administrator privileges.  Look in the file EcompSdkDMLMySql.sql for the sole row added to 
the FN_USER table.  Use the username and password from that row to login at this URL in the 
running application.  Use the application deployment (context) name chosen above to form the
proper url, it will be something like this:

	http://servername.openecomp.org:port/dmaap-bc-app/login_external.htm

6.5 Import Users

For testing purposes ONLY, users may be imported from WEBPHONE after logging in to the 
application. Find the Profile part on the left-hand menu, click on Import From WEBPHONE, and 
import users. Testers can then logon via the CSP Global Log On process starting with this URL:

	http://servername.openecomp.org:port/dmaap-bc-app/login.htm

For normal usage, users are configured via the ECOMP Portal after the application has been
on-boarded, as discussed in the next section.


7.O ON-BOARD TO ECOMP PORTAL

The application must be on-boarded to an appropriate instance of the ECOMP Portal. 

This section summarizes the steps that must be done.

7.1 Define Users and Roles

Login directly to the application as discussed above and create roles.

7.2 Determine URLs

Determine the URLs where the application is available.

7.2.1 The first URL to enter is the main application landing page, and in general 
must use HTTPS; for example:
	
	https://www.server.openecomp.org:port/dmaap-bc-app/dbc/

7.2.2. The second URL to enter is the REST endpoint, also known as the "aux" API where
the SDK-core library listens for requests to manage roles and users.  This should use
HTTPS but must NOT use a WebJunction URL; it probably points to a load balancer site.
For example:

	https://server.openecomp.org:port/dmaap-bc-app/api	

7.3 Configure Portal

An ECOMP Portal administrator must use the Portal on-boarding screen to create/register 
this application.  

7.3.1 This screen accepts the URLs from the previous step. 

7.3.2 This screen accepts an application thumbnail image. 

7.3.3. The onboarding process will cause new UEB key information to be generated
and emailed to the on-boarding user.  This information must be entered in the 
application configuration file(s).  

7.4 Add Application Users from Portal

After successful on-boarding, the Portal should be able to manage users in the remote
application.  Use the User Management feature to provision new users on the application.

7.5 Test Access from Portal

The Portal will display a tile on the applications home screen.  Click the tile.  
This should open a tab in the user's browser with the DBC web application.  


8.0 POST MAINTENANCE WINDOW WORK

N/A


9.0  ROLLBACK PROCEDURE

To restore the previous Data Bus Controll App version, stop the server
and remove the new version:

   service tomcat stop
   rm /opt/app/tomcat/webapps/dmaap-bc-app.war
   rm -rf /opt/app/tomcat/webapps/dmaap-bc-app

Then restore the old files.

Start the server to deploy the WAR file, and stop again:
  service tomcat start; sleep 30; service tomcat stop

Copy in property files:
  cp /opt/app/tomcat/webapps/dmaap-bc-app-DATE/WEB-INF/conf/system.properties    /opt/app/tomcat/webapps/dmaap-bc-app/WEB-INF/conf/system.properties
  cp /opt/app/tomcat/webapps/dmaap-bc-app-DATE/WEB-INF/classes/portal.properties /opt/app/tomcat/webapps/dmaap-bc-app/WEB-INF/classes/portal.properties

Finally restart the server
  service tomcat start