Configuring load balancing for Rational Publishing Engine document generation on WebSphere Application Server

Learn how to configure the Rational® Publishing Engine applications in a clustered environment.

Before you begin

For general information about how load balancing works with WebSphere® Application Server, see the Introduction: Clustering and Creating clusters topics in the WebSphere Application Server 8.0 Information Center.

About this task

1: Reviewing the WebSphere topology

To set up a clustered environment, you start by creating a distributed IBM WebSphere Application Server Network Deployment topology. Set up the following hosts:

About this task

The following table shows the roles for setting up a clustered environment:
Table 1. Host Names
Machines Roles Host
Machine1 Deployment manager, Node1 dm.example.org
Machine2 Node2 and Node3 nodes.example.org
Machine3 IBM HTTP Server (IHS) and IBM Web Server Plug-ins ihs.example.org
Machine4 MCSERVER mcserver.example.org
Machine5 Storage location storage.example.org
Machine6 RPE client rpeclient.example.org
Note:
  • dm.example.org: This server hosts an installation of IBM WebSphere Application Server Network Deployment V8.0.0.5 64-bit with Deployment Manager and Node agent.
  • nodes.example.org: This server hosts an installation of IBM WebSphere Application Server Network Deployment V8.0.0.5 64-bit with Node Agent.
  • ihs.example.org: This server hosts an installation of IBM WebSphere Application Server Network Deployment V8.0.0.5 64-bit with Node Agent, IBM HTTP Server V8.0.0.5 64-bit with WebSphere IHS plug-in V8.0.0.5.
  • mcserver.example.org: This server hosts an installation of IBM WebSphere Application Server Network Deployment V8.0.0.5 64-bit with Rational Publishing Engine Remote Services deployed to it.
  • storage.example.org: This server is used to store the output files. Create a shared location as \\storage\rpe\files, which must use a domain account that has access to the users that are running MCSERVER, all of the nodes that are running the WAS instance.
    Note: All document generation nodes and the MCSERVER must use the same file storage location. The user account running WebSphere Application Server must have access to this file storage location.
  • rpeclient.example.org: This machine is used to perform document generation, which acts as a Rational Publishing Engine client.
Topology diagram for loading balancing environments

2: Completing the prerequisites for deploying a clustered environment

Before you can deploy a clustered environment with WebSphere Application Server Network Deployment, you must meet several prerequisites.

Procedure

3: Installing

3.1: Installing deployment manager and nodes

Install WebSphere Application Server Network Development version 8 and upgrade to Fix Pack 5.

Before you begin

Make sure that IBM Installation Manager V1.7.3 is installed.

Procedure

  1. Download WebSphere Application Server Network Deployment version 8 from Passport Advantage®.
  2. Extract the downloaded files to a location on your drive. Example: C:\was\software\was80nd
  3. Download WebSphere Application Server Fix Pack 5 from http://www.ibm.com.
  4. Extract the downloaded files to a location on your drive. Example: C:\was\software\was80nd\8.0.0-WS-WAS-FP0000005
  5. Start Installation Manager and click File > Preferences.
  6. Click Add Repository and then add the WebSphere Application Server Fix Pack repository.config file to the list. Example: C:\was\software\was80nd\8.0.0-WS-WAS-FP0000005\repository.config
  7. Click OK, and then click Install.
  8. Select the IBM WebSphere Application Server Network Deployment and Version 8.0.0.5 check boxes. Click Next.
  9. Read and accept the terms in the license agreement. Click Next.
  10. Select Create a new package group and select an installation directory. Click Next.
  11. Optional: Select the languages to install, and then click Next.
  12. Make sure that the check boxes of the following features to install are selected:
    • EJBDeploy tool for pre-EJB 3.0 modules
    • Stand-alone thin clients, resource adapters, and embeddable containers
    • Stand-alone thin clients and resource adapters
    • Embeddable EJB container
    • IBM 64-bit SDK for Java™, Version 6
  13. On the Summary page, review the summary information, and then click Install.
  14. After the installation is complete, in the Which program do you want to start section, select None to prevent a profile from being created when the installation is finished. Click Finish.

3.1.1: Creating the deployment manager profile

Create a deployment manager profile, dm.example.org, and enable administrative security by assigning a user name and password.
Procedure
  1. Start the Profile Management Tool by clicking IBM WebSphere > IBM WebSphere Application Server Network Deployment V8.0 > Tools > Profile Management Tool.
  2. Click Create.
  3. In the Environment selection screen, select Cell (deployment manager and a federated application server) as the profile type, and click Next.
  4. Select Advanced profile creation, and then click Next.
  5. Make sure that Deploy the administrative console (recommended) is selected, and then click Next.
  6. Do not change default profile name and profile directory, but note them for later. Click Next.
  7. Make sure that the host name is correct. The host name is used to address the deployment manager. For the node name and cell name, choose names that are meaningful and easy to remember. These names are used in the configuration. Click Next.
  8. Make sure that the Enable administrative security check box is selected, and enter admin for both the user name and password. You can change the user name and password later when you set up global security. Click Next.
  9. In the Security Certificate (Part1) page, select the default option and click Next.
  10. In the Security Certificate (Part2) page, update the default keystore password and click Next.
  11. On the Port Values Assignment page, carefully note the default ports. If for any reason you must change the default ports, such as the SOAP port or the HTTP secure port, be sure to note the port numbers. Click Next.
  12. In the Web Server definition page, do not select any option. Click Next.
  13. On the Profile Creation Summary page, review the configuration, and then click Create.
  14. When the installation is complete, clear the Launch the First Steps console check box, and click Finish.
Results
You created a deployment manager profile.

3.1.2: Creating a profile for Node1, Node2, and Node3

Create a profile for Node1 in dm.example.org host. Then repeat the steps for Node2 and Node3 in nodes.example.org.
Procedure
  1. Start the Profile Management Tool by clicking IBM WebSphere > IBM WebSphere Application Server Network Deployment V8.0 > Tools > Profile Management Tool.
  2. Click Create.
  3. In the Environment selection screen, select Custom Profile as the profile type, and click Next.
  4. Select Advanced profile creation, and then click Next.
  5. Enter the Profile Name as Custom01 and then click Next.
  6. On the Node and Host Names page, make sure that the host name is correct. Click Next.
  7. Make sure that the host name is correct. The host name is used to address the deployment manager. Click Next.
  8. Specify the host name, SOAP port number, and the user name and password of the deployment manager that you specified while Creating the deployment manager profile. If you are planning to federate the node later, select the Federate this node later check box. Click Next.
  9. In the Security Certificate (Part1) page, select the default option. Click Next.
  10. In the Security Certificate (Part2) page, update the default keystore password and click Next.
  11. On the Port Values Assignment page, carefully note the default ports. If for any reason you must change the default ports, such as the SOAP port or the HTTP secure port, be sure to note the port numbers. Click Next.
  12. On the Profile Creation Summary page, review the configuration, and then click Create.
  13. When the installation is complete click Finish.
  14. Repeat the steps for Node2 in nodes.example.org.
  15. Repeat the steps for Node3 in nodes.example.org.

3.1.3: Federating Node2 and Node3

Complete these steps for Node2 and then repeat for Node3.
Before you begin
Create profiles for Node2 and Node3.
Procedure
  1. In a command-line utility, navigate to the Node2 bin directory. Example: C:\Program Files (x86)\IBM\WebSphere\AppServer\profiles\Custom02\bin
  2. Run the command: addNode.bat <Deployment Manager IP Address> <Port>
  3. Wait for the command to complete and the message Node has been successfully federated to display.
  4. Repeat these steps for Node3.

3.2: Installing IBM HTTP Server and the web server plug-ins for WebSphere Application Server

For your clustered environment, you can install an instance of IBM HTTP Server or IBM WebSphere Proxy Server and host it on ihsproxy.example.org to act as a proxy server. The following instructions are to install IBM HTTP Server V8.0.0.5 and the web server plug-ins for WebSphere Application Server V8.0.0.5 as a proxy.

Before you begin

Make sure that IBM Installation Manager V1.7.3 is installed.

Procedure

  1. Download WebSphere Application Server Network Deployment Supplements version 8 from Passport Advantage.
  2. Extract the downloaded files to a location on your drive: Example: C:\was\software\was80ndSupp
  3. Start Installation Manager and click File > Preferences.
  4. Click Add Repository and then add the following repository.config file to the list: C:\was\software\was80ndSupp\repository.config
  5. Click OK, and then click Install.
  6. Select the IBM HTTP Server for WebSphere Application Server and IBM Web Server Plug-ins for IBM WebSphere Application Server packages to install. Click Check for Other Versions, Fixes, and Extensions and make sure that version 8.0.0.5 or later is selected. Click Next
  7. Read and accept the terms in the license agreement. Click Next.
  8. Select Create a new package group and select an installation directory. Note the installation directory for later use. Click Next.
  9. Make sure that the check boxes of the following features to install are selected:
    • IBM HTTP Server 64-bit with Java, Version 6
    • IBM 64-bit Runtime Environment for Java, Version 6
  10. Accept the default HTTP port 80. Later, you set up a secure virtual host on port 443. Click Next.
  11. On the Summary page, review the summary information, and then click Install.
  12. After the installation is complete, click Finish.

3.3: Creating and configuring clusters

Create an IBM WebSphere Application Server cluster.

Before you begin

You must set up the server and the proxy server.

Procedure

  1. Open a browser window and go to the Integrated Solutions Console at https://dm.example.org:port/ibm/console, where dm.example.org is the host name of the server that hosts the deployment manager and port is the administrative console secure port.
  2. Log in by using the user name and password that you created when you created the deployment manager profile.
  3. Click Servers > Clusters > WebSphere application server clusters. Then, click New.
  4. Enter a name for the cluster, such as RPE Cluster and clear the Prefer local check box. Click Next.
  5. On the next page, create the first member of the cluster that is based on an application server.
    1. In the Member name field, enter a name, such as RPEWS1.
    2. In the Select node field, select Node1 from the drop-down list.
    3. For the Weight, select 2.
    4. Click Next.
  6. Optional: On the next page, members can be added. If you choose to add members later, follow the instructions in section 4.3.2. If you choose to add members now, enter the member name as RPE WS2 and select the Node2 in the select Node drop-down lists. Then click Add member.
  7. Review the Summary and then click Finish.
  8. Click Save directly to the master configuration.
  9. Select the cluster and click Start. A green arrow indicates that the cluster started. As you converted an application server to a cluster, the target of the installed applications on the original application server are converted to target the cluster.
  10. To check this conversion, open the Manage Modules section of the default application:
    • Click Applications > Application Types > WebSphere enterprise applications, and click DefaultApplication.
    • In the Modules section, click Manage Modules.
    • Make sure that the RPE Cluster is listed in the Server column.

3.3.1: Adding a cluster member

After you create a node cluster, you can add a cluster member.
Procedure
  1. Open a browser window and go to the Integrated Solutions Console at https://dm.example.org:port/ibm/console, where dm.example.org is the host name of the server that hosts the deployment manager and port is the administrative console secure port.
  2. Log in by using the user name and password that you created when you created the deployment manager profile.
  3. Click Servers > Clusters > WebSphere application server cluster, and then click the cluster name that you created.
  4. In the Additional Properties section, click Cluster members.
  5. On the Cluster members page, click New.
  6. In the Member name field, enter a name for the member. Example: RPEWS2
  7. Select the node cluster that you created for respective nodes.
  8. Click Add Member.
  9. Click Next, and then click Finish.
  10. Make sure that the Rational Publishing Engine members are listed in the Servers > Server Types > WebSphere Application Servers page.
  11. Select the check box of the node and click Start.
  12. Click Save directly to the master configuration.
  13. Go to the snoop page at https://proxy_host/snoop to test the newly added member node. A snoop page lists various information about a web application, such as server name and port.

4: Synchronizing changes with nodes

Before you begin

Start all of the nodes.

Procedure

  1. Open a browser window and go to the Integrated Solutions Console at https://dm.example.org:port/ibm/console, where dm.example.org is the host name of the server that hosts the deployment manager and port is the administrative console secure port.
  2. Log in by using the user name and password that you created when you created the deployment manager profile.
  3. Click System Administration > Save changes to master repository.
  4. In the save page select the Synchronize changes with Nodes check box.
  5. Click Save.

5: Deploying the Remote services application on Deployment manager

Before you begin

In the Deployment Manager, add cluster and associated members.

Procedure

  1. Open a browser window and go to the Integrated Solutions Console at https://dm.example.org:port/ibm/console, where dm.example.org, the host name of the server that hosts the deployment manager and port, is the administrative console secure port.
  2. Log in by using the user name and password that you created when you created the deployment manager profile.
  3. Deploy the Remote services application. See Manually deploying the Remote services application on WebSphere Application Server for more details.
    Note: While you deploying the Remote services application, which is step 8 in information center topic above about the Map modules to servers window, in the Clusters and Node option, select the cluster that is created as described in 3.3: Creating and configuring clusters then proceed with the normal deployment.

6: Deploying the Remote services application on MCSERVER host

Procedure

Deploy the Remote services application. See Manually deploying the Remote services application on WebSphere Application Server for more details.

7: Defining the flags in Java Virtual Machine (JVM) custom properties

Before you begin

Install the Remote services application on the Deployment manager and MCSERVER machine.

Procedure

  1. Open a browser window and go to the Integrated Solutions Console at https://dm.example.org:port/ibm/console, where dm.example.org is the host name of the server that hosts the deployment manager and port is the administrative console secure port.
  2. Log in by using the user name and password that you created when you created the deployment manager profile.
  3. Expand Servers > Server Types.
  4. Click WebSphere application servers. Members with associated Nodes and Cluster are listed.
  5. Open the server properties of member1 by clicking the server name, such as RPEWS1.
  6. In the Server infrastructure section, expand Java and Process Management.
  7. Click Process definition.
  8. In the Additional Properties section, click Java Virtual Machine.
  9. Click New to add each of the encoding flags:
    1. Settings on the Remote services node (MCSERVER) that host the single MC instance:
      • com.ibm.rational.rpe.remote.filestore=\\storage\rpe\files
    2. Settings on the Remote services nodes (MCCLIENT) which uses the sole MC instance:
      • com.ibm.rational.rpe.remote.filestore=\\storage\rpe\files
      • com.ibm.rational.rpews.url=http://<mcserver IP address>:<port>/rpews/monitor
      • -Dcom.ibm.rational.rpews.usr=user
      • -Dcom.ibm.rational.rpews.pwd=password
      • com.ibm.rational.rpe.remote.debug=true
      • com.ibm.ws.classloader.encodeResourceURLs=false
      Note: Define these flags in all the Nodes (Node1, Node2, Node3). All document generation nodes and the MCSERVER must use the same file storage location. The user account running WebSphere Application Server must have access to this file storage location.
  10. Click OK.
  11. Restart the Remote services application.

Example

Note: If nodes created under the same WebSphere Application Server instance are sharing the same derby database, set the below Java Runtime Environment flags in each Node so that it creates separate database instances. If these flags are not defined in WebSphere Application Server, then when the Remote services Monitor & Control URL is accessed, there is a chance of encountering a 500 error.

some node A: com.ibm.rational.rpe.monitor.dbconnectionurl=jdbc:derby:rpe_monitor1;create=true

some other node: com.ibm.rational.rpe.monitor.dbconnectionurl=jdbc:derby:rpe_monitor2;create=true

8: Configuring IBM HTTP Server

Before you begin

Make sure that IBM HTTP Server is installed on ihs.example.orghost. Also, make sure IBM WebSphere Application Server Network Deployment V8.0.0.5 64-bit with Node Agent is installed on the ihs.example.orghost and federated the node to Deployment manager.
  • Complete section 4.1 for installing the WebSphere Application Server Network Deployment.
  • Complete section 4.1.2 for creating the profile.
  • Complete section 4.1.4 to federate the Node to deployment manager.

Procedure

  1. Open a browser window and go to the Integrated Solutions Console at https://dm.example.org:port/ibm/console, where dm.example.org is the host name of the server that hosts the deployment manager and port is the administrative console secure port.
  2. Log in by using the user name and password that you created when you created the deployment manager profile.
  3. Click Servers > Server types > web servers.
  4. Click New.
  5. Enter the server name, such as webserver1.
  6. Select the node that is federated from ihs.example.orghost and select IBM HTTP Server as the type.
  7. Click Next.
  8. Select the WebServer template IHS. Click Next.
  9. Point to the corresponding IHS and Plugin installation location path. Click Next.
  10. Confirm the new Webserver.
  11. Click Finish.

9: Configuring IHS WebSphere plug-in

Before you begin

Make sure that IBM HTTP Server is configured.

Procedure

  1. In a command-line utility, navigate to the WebSphere plug-ins bin directory. Example: C:\IBM\WebSphere\Plugins\bin
  2. Run the following command: ConfigureIHSPlugin.bat -plugin.home <pluginInstallRoot> -plugin.config.xml <PluginConfigFile> -ihs.conf <httpdConfFile>

    Example: ConfigureIHSPlugin.bat -plugin.home C:\IBM\WebSphere\Plugins -plugin.config.xml C:\IBM\WebSphere\Plugins\config\webserver1\plugin-cfg.xml -ihs.conf C:\IBM\HTTPServer\conf\httpd.conf

  3. After the command completes successfully, access the WebSphere Application Server default application through the IHS by checking the snoop page at https://<ihs host IP address>/snoop to test the added member node.

Example

Whenever a user deploys or modifies the installedApps, you must regenerate the plug-in through the administrative console, which modifies the plugin-cfg.xml:
  1. Log in to https://dm.example.org:port/ibm/console.
  2. Click Servers > Server Types > Web servers.
  3. Select the webserver and click Generate Plug-in.

Sometimes even after regenerating, the plugin-cfg.xml file is not updated in the plug-in location. If the plugin-cfg.xml file does not update, manually copy the plugin-cfg.xml file from generated location to the WebSphere Application Server plug-in directory location.

Deployment Manager location in dm.example.org

<WAS_HOME>\profiles\Dmgr01\config\cells\<DMGR_NODE>\nodes\<IHS_Node>\servers\<Web server name>

WebSphere Application Server webserver location in ihs.example.org

<WAS_HOME>\plugins\config\<webserver>

Example:

Copy the plugin-cfg.xml file from the C:\Program Files (x86)\IBM\WebSphere\AppServer\profiles\Dmgr01\config\cells\cldegddeCell01\nodes\cldegddmNode01\servers\webserver1 directory to the C:\IBM\WebSphere\Plugins\config\webserver1 directory.

Make sure the generated plugin-cfg.xml file contains the items such as UriGroup, VirtualHostGroup Name, and Server Name. If any items are missing, manually copy and paste them in.

plugin-cfg.xml example: URI group for the Remote services:

<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/rpews/*"/>

<PrimaryServers>
	<Server Name="cldegddeNode02_RPEWS1"/>
	<Server Name="cldegddfNode02_RPEWS2"/>
	<Server Name="cldegddfNode03_RPEWS3"/>
</PrimaryServers>

10: Testing the load balancing

Before you begin

  1. Make sure Remote services application is up and running successfully for all of the nodes.
  2. Make sure MCSERVER is up and running.
  3. The shared location for storing the output files is shared with the users that are running MCSERVER, all the nodes running the WebSphere Application Server instance.
  4. Prepare some Rational Publishing Engine clients. For example: 14 .dsx files. Each client is pointing to the IHS URL. Example: http://<ihs machine IP address>/rpews/docgen

Procedure

Start all the Rational Publishing Engine clients concurrently by using a batch file.

Results

We can see that the requests are now getting load balanced. When 14 requests hit the server, 7 requests start the document generation and remaining requests are in queue. In this test, all of the nodes (Node1, Node2, and Node3) were up and running.

11: Troubleshooting issues with clustered topologies

If you encounter SRVE0255E, use these steps to correct the issue.

About this task

SRVE0255E: A WebGroup/Virtual Host to handle /rpews has not been defined.

The error SRVE0255E states that A WebGroup/Virtual Host to handle /{ApplicationContext}/admin has not been defined. This error occurs when the port number of the WC_defaulthost_secure server is not registered in the virtual host list.

Procedure

To troubleshoot this issue:

  1. In the administrative console, click Environment > Virtual hosts.
  2. Click default host. In the Additional Properties section, click Host Aliases.
  3. Click New. Add the host name and port number of the WC_defaulthost_secure server to the list. Click OK.
  4. Click Save directly to the master configuration and restart the WebSphere Application Server node.

Results

Load balancing configuration is now complete.

What to do next

Configure the remote services listed on the http://server:port/rpews/ page. See Remote services URLs for an explanation of how each URL is used and tasks for configuring each of the features.

Feedback