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, 363 insertions, 0 deletions
diff --git a/dcae_dmaapbc_webapp/dbc-app-deployment-guide.txt b/dcae_dmaapbc_webapp/dbc-app-deployment-guide.txt new file mode 100644 index 0000000..2169363 --- /dev/null +++ b/dcae_dmaapbc_webapp/dbc-app-deployment-guide.txt @@ -0,0 +1,363 @@ + + 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 |