Portal Express, Version 6.0
Operating systems: i5/OS, Linux, Windows
Install and configuring a Personalization Server cluster
These instructions describe how to install the Personalization Server in a cluster environment and do not involve the installation or configuration of WebSphere Portal Express.
- 1: Preliminary information and procedures
- 2: Installing Personalization Server
- 2.1: Using the addNode command
- 2.2: Approach 1. Installing Personalization Server on a federated WebSphere Application Server node
- 2.3: Approach 2. Installing Personalization Server on a separate WebSphere Application Server node not managed by WebSphere Application Server Network Deployment
- 3: Setting up the cluster
- 3.1: Creating the cluster
- 3.2: Creating additional cluster members
- 3.3: Updating Personalization properties in the cluster
- 4: Uninstalling Personalization Server
The Personalization Server enables you to deploy applications that have been developed with WebSphere Portal Express, serve personalized content to users, and record site metrics, without requiring that WebSphere Portal Express also be present on the machine. While rules may be executed from any WebSphere Application Server installation, a full WebSphere Portal Express installation is still required as a workspace for authoring rules and campaigns.
Troubleshooting note: The latest information regarding known issues with the installation and service of WebSphere Application Server and IBM® WebSphere® Application Server Network Deployment is located in the WebSphere Portal Express release notes. In addition to the troubleshooting information provided in the information center, refer to the release notes and the WebSphere Application Server support site to help diagnose and correct problems.
1: Preliminary information and procedures
This section explains how to install Personalization Server in a clustered environment using WebSphere Application Server and IBM WebSphere Application Server Network Deployment. Cells, which are sets of nodes, clusters, applications and additional configuration, are maintained by a central deployment manager that is responsible for maintaining the status of each node in the cell. Refer to the appropriate information center for information:- Windows and Linux: See the WebSphere Application Server Information Center: http://www.ibm.com/software/webservers/appserv/was/library/
- i5/OS:
WebSphere Application Server for OS/400 information center:http://publib.boulder.ibm.com/infocenter/wsdoc400/v6r0/index.jsp
The cluster environment setup in the following sections is described according to the following topology:
- DM01 - the WebSphere Application Server Network Deployment node
- WP01 on NODE01 - the first Personalization Server in the cell
- WP02 on NODE02 - the second Personalization Server in the cell (horizontal scaling only)
You will install each Personalization Server instance on a dedicated WebSphere Application Server profile, bring it under deployment manager control if it is not already federated into a cell, and finally add it to the cluster after it is completely configured.
If you have not already installed and configured WebSphere Application Server for your environment, refer to the appropriate Information Center before continuing.
2: Installing Personalization Server
When installing Personalization Server into a cluster environment, you can approach the installation process in two ways:
- Approach 1. Install Personalization Server on a federated WebSphere Application Server node. With this approach, you install Personalization Server on a WebSphere Application Server node that has already been federated into a cell and is actively managed by the deployment manager.
- Approach 2. Install Personalization Server on a separate WebSphere Application Server node that is not managed by a deployment manager. With this approach, you install Personalization Server on a stand-alone node and then federate the node into a cell that is managed by the deployment manager for that cell.
It is not necessary to use the same approach for every node when installing Personalization Server on multiple nodes in a cell. Select an appropriate approach for each node, according to whether the node is federated into a cell.
2.1: Using the addNode command
This section provides information on the addNode command, which is used in the installation approaches described below to add a WebSphere Application Server node to a managed cell.
After the addNode command completes successfully, the cell name of the configuration on the node that you added is changed from the base cell name to the deployment manager cell name.
Note on Java heap size: Before running the addNode command, ensure that you have updated the addNode script to increase the maximum heap size for Java commands, as described in Planning for cluster.
To add a node to the deployment manager cell, enter the addNode command on one line on the server system to be added:
- Windows:
was_profile_root\bin\addNode.bat deployment_manager_host deployment_manager_port -username admin_user_id -password admin_password [-includeapps] [-trace] [-ulimit]
- Linux:
was_profile_root/bin/addNode.sh deployment_manager_host deployment_manager_port -username admin_user_id -password admin_password [-includeapps] [-trace] [-ulimit]
- i5/OS:
app_server_root/bin/addNode deployment_manager_host deployment_manager_port -profileName profile_root -username admin_user_id -password admin_password -startingport startingport [-includeapps] [-trace] [-ulimit]
where profile_root is the name of the WebSphere Application Server profile where WebSphere Portal Express is installed; for example, wp_profile and startingport is the port number used as the base port number for all node agent and Java Messaging Service (JMS) server ports created during the running of the addNode command.
where:
- was_profile_root is the profile directory on WebSphere Application Server.
- deployment_manager_host is the deployment manager host name.
- deployment_manager_port is the deployment manager SOAP connector-address. The default value is 8879.
- admin_user_id is the WebSphere Application Server administrative user name. This parameter is optional but is required if security is enabled.
- admin_password is the administrative user password. This parameter is optional but is required if security is enabled.
Parameters:
- -includeapps
- The -includeapps parameter is optional. This parameter should only be used if there are enterprise applications already installed on this node that need to be added to the deployment manager's master configuration. If you do not specify this flag, any application servers that are defined on this node will be included in the deployment manager's configuration, but they might not be functional without their corresponding enterprise applications. If the application already exists in the cell, a warning is generated and the application is not installed into the cell.
- -trace
- The -trace parameter is optional. This parameter generates trace information that is stored in the addNode.log file for debugging purposes.
- -ulimit
- The -ulimit parameter is optional and is used to specify the number of supported open files. The default setting is typically sufficient for most applications. If the value is set too low, one of the following error message might occur:
- File open error
- Memory allocation error
- Connection establishment error
Refer to the appropriate WebSphere Application Server information center for specific steps on setting the -ulimit parameter:
- Windows and Linux: WebSphere Application Server Network Deployment information center
- i5/OS:
2.2: Approach 1. Installing Personalization Server on a federated WebSphere Application Server node
This section describes how to federate two separate WebSphere Application Server nodes into a cell that is managed by the deployment manager on the WebSphere Application Server Network Deployment system (DM01) and then install an instance of Personalization Server (WP01 and WP02) on each of those nodes. Below are detailed steps for implementing this scenario.
When you remove a node from a managed cell, the application server on that node reverts to the state it had at the time it was originally federated. Consequently, if you install Personalization Server on a node that has already been federated into a cell and then later remove that node from the cell, Personalization Server will not be usable on the resulting stand-alone server.
i5/OS limitation: WebSphere Portal Express installation is not supported on a federated node in an i5/OS environment. If you are building a WebSphere Portal Express cluster on i5/OS, use the instructions in the following section to install WebSphere Portal Express and then federate the node: Approach 2. Install Personalization Server on a separate WebSphere Application Server node that is not managed by a deployment manager
2.2.1: Federating the WebSphere Application Server nodes
- Prerequisites for federating the WebSphere Application Server nodes (NODE01 and NODE02):
- WebSphere Application Server must be installed and operational on each node.
- WebSphere Application Server Network Deployment must be installed on DM01 to the same release level as the profiles of WebSphere Application Server.
- If security is enabled, the same security settings must be specified for the WebSphere Application Server Network Deployment system and for each WebSphere Application Server node, or each Application Server node must not have global security enabled. When the node is federated, the deployment manager's security settings will propagate to the node.
- Add NODE01 to the deployment manager (DM01) cell by entering the addNode command. Specify the -includeapps parameter only if there are enterprise applications already installed on this node that need to be added to the deployment manager's master configuration. Refer to Using the addNode command for command syntax and other information.
- Repeat the previous step for NODE02, if you are setting up a horizontal cluster. This step is not required if you are using vertical scaling.
- If any application servers and enterprise applications were already installed before you added the node to the cell, verify that they still function properly.
The Personalization install accesses the node to which it is installing via localhost. Make sure that your virtual hosts are configured in such a way that you can access the node applications through localhost before continuing.
- Refer to 3: Setting up the cluster if you are ready to set up your cluster.
- Prerequisites for installation of first Personalization Server instance (WP01):
- The WebSphere Application Server nodes must be installed with any fix packs or interim fixes required by Personalization Server. The nodes must also be operational and federated into the deployment manager cell.
- WebSphere Application Server Network Deployment must be installed on DM01 to the same release level as the profiles of WebSphere Application Server.
- The remote database server must be installed and operational.
- Install Personalization Server.
Refer to the appropriate instructions for installing on an existing WebSphere Application Server, according to your platform:
- Windows and Linux:
- Verify that Personalization Server is operational after installation.
- Configure the node to use an external Web server. By default, Personalization Server uses its own HTTP service for client requests. However, an external Web server is required to take advantage of features such as workload management. Refer to the Configuring your Web server topic for information on how to configure Personalization Server to use an external Web server.
- Verify that Personalization Server is operational with the new external Web server configuration.
- Once complete, the federated servers will be visible in the Network Deployment Admin Console > Servers > Application Server view. Start and verify the operability of the Personalization Server instance.
2.2.3: Installing WP02 (horizontal scaling only)
Vertical cluster note: If you intend to use Personalization Server in a vertical scaling topology, you can disregard the steps in this section and skip to Setting up the cluster.
- Install the second Personalization Server instance, but do not configure it. Rather choose the option that allows you to copy files.
- In pzn_root/config, edit the following files so that they are correct for your environment:
- wpconfig.properties
- wpconfig_dbdomain.properties
- wpconfig_dbtype.properties
- Configure WP02 to function in the managed environment by running the following command from the pzn_root/config directory:
- Windows:
WPSconfig.bat cfg-pzn-secondary-node
- Linux:
./WPSconfig.sh cfg-pzn-secondary-node
- Windows:
- Verify that the secondary instance is now operational.
- For each secondary cluster member you create on WP01, configure Personalization work managers by running the following commands from the pzn_root/config directory:
- Windows:
- WPSconfig.bat - DServerName=secondary_cluster_member init
- WPSconfig.bat action-create-workmanager-cmapi
- WPSconfig.bat action-create-workmanager-cleanup-daemon
- WPSconfig.bat action-create-workmanager-jcr
- WPSconfig.bat action-create-workmanager-ci
- WPSconfig.bat action-create-all-workmanagers-pzn
- Linux:
- ./WPSconfig.sh - DServerName=secondary_cluster_member init
- ./WPSconfig.sh action-create-workmanager-cmapi
- ./WPSconfig.sh action-create-workmanager-cleanup-daemon
- ./WPSconfig.sh action-create-workmanager-jcr
- ./WPSconfig.sh action-create-workmanager-ci
- ./WPSconfig.sh action-create-all-workmanagers-pzn
- Windows:
- Restart the cluster member.
2.3: Approach 2. Installing Personalization Server on a separate WebSphere Application Server node not managed by the deployment manager
This section describes how to set up two separate Personalization Server instances (WP01 and WP02) on two dedicated systems and add them to the Deployment Manager (DM01). Below are detailed steps for implementing this scenario.
- Prerequisites for installation of first Personalization Server instance (WP01):
- Deployment Manager must be installed on DM01 to the same release level as the profiles of WebSphere Application Server.
- The remote database server must be installed and operational.
- Install Personalization Server.
Refer to the appropriate instructions, according to your platform:
- Windows and Linux:
- Verify that Personalization Server is operational after installation.
- If you installed Personalization Server on a WebSphere Application Server node with security already enabled, ensure that the WebSphere Application Server Network Deployment machine is configured with the same security settings as Personalization Server before adding the secured Personalization Server node to the deployment manager cell. Custom user registry note: If you are using a custom user registry for security, ensure that the required WMM JAR files are present on the WebSphere Application Server Network Deployment machine. For details on using a custom user registry for security in a cluster, refer to Enabling WebSphere Application Server security for WebSphere Portal Express.
- Add WP01 to the deployment manager cell by entering the addNode command. Ensure that you include the -includeapps parameter. Refer to Using the addNode command for command syntax and other information.
- Once complete, the federated servers will be visible in the deployment manager administrative console in the Servers > Application Server view. Start and verify the operability of the Personalization Server instance.
2.3.2: Installing WP02 on a separate WebSphere Application Server node not managed by the deployment manager (horizontal scaling only)
The procedure for installing WP02 is nearly identical to that for installing WP01, except that WP02 is federated into the cell without including any of its applications. This is because the cell can contain only one set of these applications, and the applications have already been included when WP01 was federated.
- Install second Personalization Server instance. Refer to the appropriate instructions, according to your platform:
- Windows and Linux:
- Add WP02 to the deployment manager (DM01) cell by entering the addNode command. Do not include the -includeapps parameter. Refer to Using the addNode command for command syntax and other information.
- It is important not to use the -includeapps option. The applications will not be transferred as they are already in the deployment manager's master configuration.
- Applications stored in the master configuration are still only assigned to WP01. In order to share them with WP02 and any additional nodes, a cluster must be created.
2.3.3: Configuring the nodes to operate in a cluster
This section describes the steps to configure Personalization and Deployment manager to use a cluster. Once you have completed these steps, you may skip to Section 3.3: Updating Personalization properties in a cluster.
- On WP01, open pzn_root/config/wpconfig.properties and set the ClusterName property to the name of the cluster you wish to create on the deployment manager. Make sure that all of the security settings are still accurate for your environment. Run the following command from pzn_root/config:
- Windows:
WPSconfig.bat cluster-setup
- Linux:
./WPSconfig.sh cluster-setup
- Windows:
- Horizontal Scaling Only: On WP02, open pzn_root/config/wpconfig.properties and set the ClusterName property to the name of the cluster you just created on the deployment manager. In addition, make sure that the property PrimaryNode is set to false. Make sure that all security settings are still accurate for your environment. Run the following command from pzn_root/config:
- Windows:
WPSconfig.bat cluster-setup
- Linux:
./WPSconfig.sh cluster-setup
- Vertical Scaling Only: Run the following command from pzn_root/config to configure secondary cluster members:
- Windows:
- WPSconfig.bat -DPrimaryNode=false - DServerName=new_cluster_member cluster-setup
- WPSconfig.bat - DServerName=secondary_cluster_member init
- WPSconfig.bat action-create-workmanager-cmapi
- WPSconfig.bat action-create-workmanager-cleanup-daemon
- WPSconfig.bat action-create-workmanager-jcr
- WPSconfig.bat action-create-workmanager-ci
- WPSconfig.bat action-create-all-workmanagers-pzn
- Linux:
- ./WPSconfig.sh -DPrimaryNode=false - DServerName=new_cluster_member cluster-setup
- ./WPSconfig.sh - DServerName=secondary_cluster_member init
- ./WPSconfig.sh action-create-workmanager-cmapi
- ./WPSconfig.sh action-create-workmanager-cleanup-daemon
- ./WPSconfig.sh action-create-workmanager-jcr
- ./WPSconfig.sh action-create-workmanager-ci
- ./WPSconfig.sh action-create-all-workmanagers-pzn
- Windows:
3: Setting up the cluster
Once the Personalization Server application servers reside on the federated WebSphere Application Server nodes, you can create a cluster and add the Personalization Server instances (WP01 and WP02) as cluster members. This section also describes how to add additional cluster members after the cluster has been created.
- To create the cluster, use the administrative console on the deployment manager. Start the administrative console by opening a browser and entering http://DM01:9060/admin in the address bar, where DM01 is the deployment manager node or host name.
i5/OS users: The profile referred to here was created from the app_server_root/bin directory. - Click Servers > Clusters in the navigation tree, and click New.
- Enter the basic cluster information:
- Define the cluster name.
Do not use spaces in the cluster name.
- Check the box Prefer local enabled.
- Check the box Create Replication Domain for this cluster.
- Select the option Select an existing server to add to this cluster and then choose server Personalization_Server on node WP01 from the list.
- Check the box Create Replication Entry in this Server.
- Click Next.
- Define the cluster name.
- Create the second cluster member.
- Define the name of cluster member.
Do not use spaces in the cluster member name.
- Select the appropriate node, depending on the cluster topology you are using:
- Horizontal: WP02
- Vertical: WP01
- Select the appropriate HTTP port setting, depending on the cluster topology you are using:
- Horizontal: Uncheck the box Generate Unique HTTP Ports.
- Vertical: Check the box Generate Unique HTTP Ports.
- Check the box Create Replication Entry in this Server.
- Click Apply and then click Next to view the summary.
- Define the name of cluster member.
- To create the new cluster, click Finish.
- To save your changes, click Save, and then click Save again to confirm the changes and update the deployment manager configuration.
- When you have completed the steps above, the cluster topology can be viewed from the Servers > Cluster Topology view.
- The application server view will list the new server cluster members.
- Save your changes and resynchronize the nodes:
- In the administrative console for the deployment manager, click Save on taskbar, and save your administrative configuration.
- Select System Administration > Nodes, select the node from the list, and click Full Resynchronize.
- Regenerate the Web server plug-in using the deployment manager administrative console.
- WebSphere Application Server Version 6: Select Servers > Web Servers in the deployment manager administrative console, select a Web server, and then click Generate Plug-in.
- Edit the nd_root/config/cells/plugin-cfg.xml file and change any directory structure occurrences specific to the WebSphere Application Server Network Deployment machine to match the directory structure used on the Web server. For example, references to install_dir/WebSphere/DeploymentManager would be replaced with install_dir/WebSphere/AppServer.
- If you are using a remote Web server, copy the updated plug-in configuration file (nd_root/config/cells/plugin-cfg.xml) to the Web server's plug-in configuration directory.
- Stop and start the Web server.
- Restart all nodes in the cluster.
3.2: Creating additional cluster members
Although it is possible to define all cluster members at the same time you initially create the cluster (as described in Creating the cluster), you might also need to add cluster members at some later time, after the cluster has already been configured. This section provides instructions for adding cluster members in both horizontal and vertical scaling topologies for an existing cluster.
3.2.1: Creating horizontal cluster members
Cluster members in a horizontal scaling topology reside on different nodes in the cell. To create an additional cluster member in a horizontal cluster...
- Install Personalization Server on the new node in the cell. Follow the instructions in Installing Personalization Server, depending on whether the node is already federated into the cell.
- Access the administrative console on the deployment manager by opening a browser and entering http://DM01:9060/admin in the address bar, where DM01 is the deployment manager node or host name. The port number might differ based on your installation.
- Click Servers > Clusters in the console navigation tree, select the cluster name, and then click Cluster members from the list of additional properties.
- Click New to create the cluster member.
- Define the name of cluster member.
Do not use spaces in the cluster member name.
- Select the node where you installed the new instance of Personalization Server.
- Uncheck the box Generate Unique HTTP Ports.
- Click Apply and then click Next to view the summary.
- Define the name of cluster member.
- Click Finish, and save the changes.
- The new cluster topology can be viewed from the Servers > Cluster Topology view.
- The Servers > Application Servers view will list the new server cluster members.
- Regenerate the Web server plug-in using the deployment manager administrative console.
- Stop and start the Web server.
- Restart all nodes in the cluster.
3.2.2: Creating vertical cluster members
Cluster members in a vertical scaling topology reside on the same node in the cell. To create an additional cluster member in a vertical cluster...
- Access the administrative console on the deployment manager by opening a browser and entering http://DM01:9060/admin in the address bar, where DM01 is the deployment manager node or host name. The port number might differ based on your installation.
- Click Servers > Clusters in the console navigation tree, select the cluster name, and then click Cluster members from the list of additional properties.
- Click New to create the cluster member.
- Define the name of cluster member.
Do not use spaces in the cluster member name.
- Select an existing node where Personalization Server is installed.
- Check the box Generate Unique HTTP Ports.
- Click Apply and then click Next to view the summary.
- Define the name of cluster member.
- Click Finish, and save the changes.
- The new cluster topology can be viewed from the Servers > Cluster Topology view.
- The Servers > Application Servers view will list the new server cluster members.
- Regenerate the Web server plug-in using the deployment manager administrative console.
- Stop and start the Web server.
3.3: Updating Personalization properties in the cluster
Personalization Server provides two property files that you can modify to customize the Personalization feature. These files are not managed by the WebSphere Application Server deployment manager. This means that if you make any changes to these files on a node in the cluster, those changes are not transferred to other nodes when you perform a synchronization of the cluster members. Instead manually copy the following properties files to each node in the cluster:
- pzn_root/pzn/v6.0/lib/config/services/PersonalizationService.properties
- pzn_root/pzn/v6.0/lib/config/services/FeedbackService.properties
- pzn_root/pzn/v6.0/lib/config/services/LikeMindsService.properties
4: Uninstalling Personalization Server
- Ensure that you have removed the Personalization Server node from the cell.
- Uninstall the product files from the node by following the instructions in Uninstalling the Personalization Server.