diff options
Diffstat (limited to 'dcae_dmaapbc_webapp/dbc-app-deployment-guide.txt')
| -rw-r--r-- | dcae_dmaapbc_webapp/dbc-app-deployment-guide.txt | 363 |
1 files changed, 0 insertions, 363 deletions
diff --git a/dcae_dmaapbc_webapp/dbc-app-deployment-guide.txt b/dcae_dmaapbc_webapp/dbc-app-deployment-guide.txt deleted file mode 100644 index 2169363..0000000 --- a/dcae_dmaapbc_webapp/dbc-app-deployment-guide.txt +++ /dev/null @@ -1,363 +0,0 @@ - - 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 |