Installing Lotus ActiveInsight on a Portal cluster

Installing Lotus ActiveInsight on a Portal cluster

Required environment:
Software

• IBM WebSphere Portal v6.1.5
• IBM WebSphere Application Server v6.1.0.23 or v7.0
• LDAP Server supported by IBM WebSphere Portal v6.1.5
• IBM DB2 v9.1.x or v9.5.x or Oracle
• HTTP Server supported by the version of IBM WebSphere Application Server being used.

Hardware layout

• 1 server running the HTTP server software
• 1 server running the Database Server software
• 1 server running LDAP Server software
• 1 server to run the Deployment Manager node
• 1 or more servers running WebSphere Portal cluster nodes

The above server listed roughly matches the recommended layout that the IBM WebSphere Portal Infocenter details for a production deployment. http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/topic/com.ibm.wp.ent.doc_v6101/plan/top_horizontalscaling.html

It is possible, for smaller deployments or for test environments to combine the functions of the servers listed. Doing so might reduce the full abilities of the clustered environment.

Procedure:
The procedures below will assume the use of IBM DB2 and IBM HTTP Server on the supporting servers.

1. Install the WebSphere Cluster as detailed in the Portal Infocenter. http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp?topic=/com.ibm.wp.ent.doc_v6101/install/production.html. Another excellent guide to doing this can be found in the Step-by-Step Cluster Guide for IBM WebSphere Portal v6.1 http://www-01.ibm.com/support/docview.wss?rs=688&ca=port&uid=swg21313184 . Once complete a functioning portal cluster will be available.
2. Obtain the Lotus Activeinsight v6.1.5 installation software via CD or electronic distribution. If a CD then mount the CD on the Portal Primary node so that the files can be accessed. If the latter, then expand the Zip file into a temporary place on the primary node.
3. Copy the LAI_DBSETUP.zip file to the Database server which will be used for the ActiveInsight database. If the database server is a Linux or Unix OS then it is best to put this file so that the DB2 instance user can access it.
1. Unzip the file.
2. Make sure that Java is in the PATH environment. The setup scripts rely on java to do much of the setup work. For example, on unix (using a 64 bit OS): export PATH=$PATH:/opt/IBM/db2/V9.1/java/jdk64/jre/bin
3. Edit the db2.properties file with the values be used to create the database and populate the system values. The default settings will assume a Windows environment. Alter as necessary.
4. Run setup_db2.bat or setup_db2.sh. The script will first display a list of the property values to be used and then if the user agrees by pressing 'Y' the script will create the database and populate it.
4. Copy the LAI_WAS_Update.zip to the Deployment Manager server
1. Unzip the file.
2. To update the wps.ear file with the ActiveInsight themes the add_ai_themes.bat or add_ai_themes.sh needs to be run. these scripts require 5 parameters:
1. Destination directory i.e. /tmp/Activeinsight or C:\ActiveInsight
2. Deployment Manager profile root i.e /opt/IBM/WebSphere/AppServer/profiles/Dmgr01 or C:/IBM/WebSphere/AppServer/profiles/Dmgr01 (Note: for Windows, here we do use a java style path separator)
3. Deployment manager SOAP port (i.e. 8879)
4. Deployment Manager admin id
5. Deployment manager admin password
3. Run the add_ai_themes script with the proper parameters. If a failure is indicated, check to see that the parameter values are correct and rerun the script.
5. Create the ActiveInsight Data source.
1. Login to the Deployment Manager Integrated Console
2. Select Resources-->JDBC-->JDBC providers
3. Set the scope to be PortalCluster (If the Portal cluster has another name this will vary)
4. Click "New" to create a new JDBC/Data source definition. For Step 1, fill in the values similar to the ones shown here. The one real choice with user discretion is the Name. A value such as laiJDBC is useful:
   
5. For Step 2 adjust the values if needed. The assumption on this panel is that the WebSphere Variables are defined which prefix the jar files in the class path. It is useful to use variable here if the nodes in the cluster are not all identically constructed. For example if one node has a C: and D: drive and the jar files required are found on the D: drive, yet another node has only a C: drive, then a variable would be needed to give proper scope and allow the data source to find the jar files on each node.
6. Step 3. Check the summary page and then click the "Finish" button to create the JDBC definition.
7. Save the changes to the WebSphere master configuration database.
8. Next create the Data source. Click on the Data sources link. On the next page click the "New" button"
   
9. Fill in the Data source forms:
   
1. Step 1 requests the Data source and JNDI name. Remember the Data source name. It will be needed during the installation of ActiveInsight on the primary node.
2. Step 2 creates the database name and server definitions. The information put here should correspond to the database created in Step 3 above.
3. Step 3 contains the user name and password needed to access the password. These values were put into the db2.properties in Step 3 above. This is possible that the records needed are already created if the authentication credentials are the same as for the Portal Data sources. Create a new record or reuse as appropriate.
4. Step 4 contains the summary and then when the "Finish" button is pressed the Data source definition is created.
5. Save the changes to the WebSphere master configuration database.
10. Test the new Data source definition. If successful, the connection should work from all the nodes in the cluster. If there is a failure, double check the definitions, make sure the database server is active and try again until a successful connection is made.
    
11. Install ActiveInsight on the primary node.
12. From the wbse_ee directory of the installation software location, start the install.sh or install.bat script.
13. The installer program will go through a number of panels asking for:
1. Location for ActiveInsight directory.
2. WebSphere Application Server directory location, Admin ID, and password
3. WebSphere PortalServer directory location, Admin ID, and password
4. Profile location used by the PortalServer (e.g. wp_profile)
5. The next panel will ask for the installation type. Here choose Cluster Primary Node
6. The next panel will display some values appropriate to the primary node of the cluster. The supplied values are likely correct, but they can be verified by looking at the Integrated console
• Portal Cluster Name: Navigate to Servers -> Clusters
• Cluster Cell Name: Navigate to System Administration -> Cell
• Deployment Manager SOAP Connection Port: The port used by wsadmin to connect to DM. Navigate to System Administration -> Deployment Manager -> Ports -> SOAP_CONNECTOR_ADDRESS
• Current Portal Server Name: The current Portal Server’s name that you install LAI onto. Navigate to Servers -> Application Servers
• Current Portal Server Port: Navigate to Servers -> Application Servers -> -> Ports -> WC_defaulthost
7. The next panel will ask for the Database Type (DB2 or Oracle), Data source name and the Schema. The default Schema is WBPM. The Data source name is the one defined in Step 5i above. Upon proceeding the installer will check the connection to the Data source.
8. The next panel will ask for a Keystore Password. The value here must be the same value put in the db2.properties (Step 3c above).
9. Next panel will ask for the Fully Qualified Host Name. If the installer can not determine this beforehand it will put "localhost' in this field. Change this as needed to the host name of the primary (i.e. yourserver.yourco.com)
10. The final panel asking for information will ask for the host name and port of the HTTP server used with the Portal.
14. The installer will start by writing the necessary files needed by ActiveInsight including jar files, keystore file sample data examples to the file system.
15. Then comes a number of steps do configure the Application server (which in this case is the Deployment Manager instance), including the installation of some EJBs as well as a verification of Data source items.
16. The Portal will then be restarted and the portlets and pages will be created.
17. If all goes well the installer will install ActiveInsight on the primary node without any complications. Should any errors occur see the troubleshooting section below.
18. Make sure all portlets, themes and skins are synchronized from primary node to secondary nodes by doing one of the following:
1. waiting long enough, or
2. restart portal, or
3. go to WAS console, find the cluster deployment manager and force a resynch from there.
19. Run the following command to activate all the 18 LAI portlets after the synchronization is finished. /PortalServer/bin/xmlaccess.sh -in /PortalUtil/activatePortlets.xml -user -password -url http://localhost:10040/wps/portal
20. If using WAS v7 the port in the URL is likely to be 10039. In any case it be found from the Integrated Console via Servers -> Application Servers -> -> Ports -> WC_defaulthost.
21. If installing on Windows, use xmlaccess.bat rather than xmlaccess.sh in the script above.
6. Install ActiveInsight on the secondary node(s).
1. From the wbse_ee directory of the installation software location, start the install.sh or install.bat script.
2. The installer program will go through a number of panels similar to that when installing the primary node. This time select Cluster Secondary node as the install type. Continue filling the installer's installation panels until the installer actually starts the installation. There will be fewer panels asking for information since a secondary node install is much simpler.
3. If all goes well the installer will install ActiveInsight on the secondary node without any complications. Should any errors occur see the troubleshooting section below.
7. Reconfigure the HTTP server to pick up the ActiveInsight applications which have a special URL context.
1. During the installation of the web server, done as part of the Portal installation, there should file in the Deployment manager profile bin directory with a name similar to 'configurewebserver1.bat' or 'configurewebserver1.sh'
2. Run this script with the following parameters configurewebserver1.sh -profileName -user -password -ihsAdminPassword
8. Restart the HTTP Server

Troubleshooting
It is often possible to recover from errors which are reported from the installer.

1. Errors during the Information gathering phase:
1. Data source cannot be verified. This can happen if the database server becomes unaccessible. As a first step use the Integrated Console to verify the Data source connection. If this is successful attempt to repeat this part of the installer using the back and next buttons (or the previous and next prompts in a console install.
2. WebSphere Administrator and/or PortalServer Administrator id/pw can't be verified. Check to see that the PortalServer node is started. Check to see if the correct values were put into the previous panels.
2. Errors during the actual installation and configuration.
1. Each task the installer runs in this phase of the installer is logged. There should be a 'cmd.txt', a 'stdout.txt' and a 'stderr.txt' for each task e.g. createdb_cmd.txt.
2. When an error happens, examine the stdout and stderr files. These often contain a clue to what went wrong. If the error can be determined, run the corresponding task found in the cmd file from a terminal window. The output from these will be written to the same windows as the command is run from. If the task runs successful, then switch back to the ActiveInsight installer and continue the install.
3. If it is not possible to recover the error at this stage, continue the install. It is likely to generate further errors before it finished. then uninstall the product on that node. Depending on when the install failure happened there are likely to be uninstall errors. For example, if it was the last install step that failed then the first uninstall step will report a problem, but pressing on the rest of the uninstall steps should work and the PortalServer should be effectively be returned to its original state.