ecomp-portal-widget-ms/widget-ms/README.md

   1 # Portal Widget Microservice
   2
   3 For security, the server listens only on localhost (127.0.0.1) and requires HTTP Basic
   4 Authentication. No outside network traffic is accepted or processed (packets never leave
   5 the host). Currently, the server uses a self signed certificate - details below.
   6
   7 ## Build Prerequisites
   8
   9 1. Java version 1.8
  10 2. Maven version 3
  11 3. Connectivity to AT&T Maven Central
  12
  13 ## Run Prerequisites
  14
  15 1. Java version 1.8
  16 2. A Mysql database using the same database as the Portal
  17
  18 ## Build and Package
  19
  20 Use maven to build and package the microservice into a jar using this command:
  21
  22         mvn clean package
  23
  24 ## Configuring
  25
  26 All configuration parameters are entered in a file called application.properties.  A version with default values can be found in the top level of this project.
  27
  28 Details about the database are configured in this file. The default entries for the database configuration are shown here:
  29
  30         spring.datasource.url=jdbc:mariadb:failover://{db_host:db_port/{portal_db}
  31         spring.datasource.username={username}
  32         spring.datasource.password=ENC({encrypted_password})
  33
  34 The HTTP server's username and password are configured in this file.  Only one username/password is used to secure the REST endpoint. The default entries for the server are shown here:
  35
  36         security.user.name={basic_auth_username}
  37         security.user.password=ENC({encrypted_basic_auth_password})
  38
  39 When you package the application into a jar file and launch the microservice using that jar, the configuration file must be in the current working directory where you launch the service.
  40
  41 ## Generating Encrypted Passwords
  42
  43 Use the following command to generate an encrypted password for the database and the
  44 micro service.  The entire command must be entered on one line; the command shown
  45 below uses backslashes to break lines for readability:
  46
  47         java -cp ~/.m2/repository/org/jasypt/jasypt/1.9.2/jasypt-1.9.2.jar \
  48                 org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI \
  49                 algorithm=PBEWithMD5AndDES \
  50                 input='YourPasswordHere' \
  51                 password='EncryptionKey'
  52
  53 Note, 'YourPasswordHere' is the actual database password, as supplied in the 'password'
  54 parameter.  The value 'EncryptionKey' is used to encrypt the input, and must be supplied
  55 at run time in one of two ways:
  56
  57 * On the command line with a JVM argument "-Djasypt.encryptor.password".  Here's an example
  58 of using maven with the Spring-Boot goal:
  59
  60         mvn -Djasypt.encryptor.password=EncryptionKey spring-boot:run
  61
  62 Here's an example of using java and the jar file:
  63
  64         java -jar dbc-microservice.jar -Djasypt.encryptor.password=EncryptionKey
  65
  66 * In the application.properties file using the key jasypt.encryptor.password.  For example:
  67
  68         jasypt.encryptor.password=EncryptionKey
  69
  70 ## Development Launch
  71
  72 Check the configuration properties in file src/main/resources/application.properties.  Then launch the microservice for development and testing like this:
  73
  74         mvn clean spring-boot:run
  75
  76 ## Production Launch
  77
  78 Ensure a valid configuration is present in file application.properties in the current working directory.  Then launch the microservice for production like this:
  79
  80         widget-service.sh start
  81
  82 ## Release Notes
  83
  84 ### Release 1702, February 2017
  85
  86 #### Consul Release Notes
  87
  88 Build 1702.3.48, 5 Feb 2017
  89 - DE264319 - Corrected spelling for output file from 'consule.out' to 'consul.out' - Please do not miss re-deploying consul build. Widget-ms build is not enough (or required) for this bug fix to be validated.
  90
  91 #### Widget-ms Release Notes
  92
  93 Build 1.2.175
  94 - Def 120258 Fixed the widget displaying issues in Internet Explorer 11
  95
  96 Build 1.2.145
  97 - Def 143148 - fixed the defect, common widgets work on Firefox version 45
  98 - Def 142432 - Widget-ms: InputStream is not getting closed in file StorageServiceImpl.java
  99
 100 Build 1.2.140
 101 - St 164888 allow partner applications to trigger a new app tab through portal
 102 - St 164847 CCD Widgets
 103 - Def 141951 Fixed the issue for inappropriate location of framework-template.js file
 104 - Def 141352 Widget Onboarding Page, download icon is not clickable in FF 45 version,  Revise widget upload service temporary storage to /tmp
 105 - St 164902 One copy of framework.js hidden in the Portal instead of being part of the widgets
 106 - St 164905 Download the widget
 107 - St 164711 Widget Personalization: Allow user to define his/her own parameters on widgets
 108 - St 164863 Widgets to use service onboarding feature
 109
 110 Build 1702.3.86
 111 - MariaDB connector / failover fix
 112
 113 Build 1702.3.79, 10 Feb 2017
 114 - Updated application.properties to correct database schema name from dbca to portal
 115 - US799260 appended complete hostname to widget certificate for irvine
 116 - US799260 appended complete hostname to consul config.json file in prod1 and prod2
 117 - US799260 fixed the bar chart issue on devn1, the bar chart shows up on devn1 Home Page
 118
 119 Build 1702.3.78, 9 Feb 2017
 120 - US799260 fixed the firefox compatibility issue; and y-scales issue in bar chart
 121 - US799260 Added the three new widgets in dashboard-widgets folder; removed all testing logs in all widgets; fixed a bug in widget-test
 122
 123 Build 1702.3.75, 07 Feb 2017
 124 DE267061 - Removed a hardcoded instance of loginId used in the query.
 125
 126 Build 1702.3.73, 06 Feb 2017
 127 DE267061 - Fixed - user should only see widgets that were uploaded against app/roles that they have OR if they were uploaded by checking All Users checkbox.
 128 Build 1702.3.71, 5 Feb 2017
 129 - Important Note: Copied all these build notes from Portal WebApp to here (widget-ms) - in order not to confuse folks, we have removed Portal's build numbers for these notes. Going forward, will add widget-ms's own build number. Also note that we've changed the version series in POM.xml from 1702.0 to 1702.3 in pom.xml - Although Jenkins/SWM overrides and doesn't care about maven's versioning, but did this to synch with what Portal Web App POM.
 130 - DE261560 Portal App: Widgets MS logs are not getting rolled over
 131 - DE261655 Unable to delete standard widgets
 132 - DE262487 EP-Portal App: News widget not adapting when tile size is changed by user
 133 - DE257516 Common widgets reload in a single tab
 134 - DE262505 Upload Duplicate Widget Issue
 135 - DE262610 Widget Microservice logging is not following EELF guidelines
 136 - DE262800 Issues with widget name this requires database modifications
 137 - DE263090 Issues with widget roles
 138 - US799260 BE now 'discovers' widget-service using Consul. If consul is not running, it fallbacks to the current implementation which is https://localhost and the port of your choosing in system.properties - Ex: localhost:8082
 139 - US799260 Fix delete feature for the three special widgets news, events, resources     widget can have spaces in its name
 140 - US799260 Widget feature:
 141   + Add the editing feature in widgetOnboarding page
 142   + Move widget catalog and onboarding to new directories
 143 - US811188 Log / Audit widgets logging in DB
 144 - US818934 Allow basic authentication
 145 - US814730 Make news / Events and Resources as widgets
 146 - US827836 Portal Widget Framework
 147
 148 ## Contact
 149
 150 Ikram Ikramullah
 151
 152 ## Certificate
 153
 154 ### Create self signed certificate
 155
 156 1. Create a self signed certificate for the microservice
 157 keytool -genkey -alias widget-microservice -storetype PKCS12 -keyalg RSA -keystore widget-keystore.p12
 158
 159 ### Import into client's trust store
 160
 161 1. Export certificate from microservice's keystore - default password is 'microservice'
 162 keytool -exportcert -keystore widget-keystore.p12 -alias widget-microservice -file widget-cert.cer
 163
 164 2. Import the exported certificate of microservice from step 1 and import it into Portal JRE's cacerts file. The location of this file is %JRE%/lib/secuirty/cacerts.
 165
 166 keytool -import -trustcacerts -keystore "C:\Program Files\Java\jre1.8.0_91\lib\security\cacerts" -noprompt -alias widget-microservice -file widget-cert.cer
 167
 168 OR
 169 ;
 170 keytool -import -trustcacerts -keystore /usr/local/add-on/jdk1.8.0_60/jre/lib/security/ -noprompt -alias widget-microservice -file widget-cert.cer
 171
 172 ### Runing on http (not https)
 173
 174 If the intent is to run this microservice without https i.e run on plain http, comment out (put a leading #) infront of all properties in 'Certificate Properties' section of application.properties - these properties are
 175
 176 server.ssl.key-store=classpath:widget-keystore.p12
 177 server.ssl.key-store-password=ENC(DiIYnAMab4u7rEW2yKhF9zBL00uU55q8)
 178 server.ssl.keyStoreType=PKCS12
 179 server.ssl.keyAlias=widget-microservice
 180
 181 ## Running service in docker
 182
 183 a). Build docker image: mvn docker:build
 184 b). Run the service in docker: docker run -p <port>:<port-in> -t <image-name>
 185 c). Check running docker containers: docker ps
 186
 187 ## Migration Instruction
 188 1. Due to changes in the existing tables, the user will have to remove all the existing widgets in 1702 release
 189 2. Re-upload the latest version of widgets under dashboard-widgets folder