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