Federating WebSphere Commerce

If you federate your WebSphere Commerce environment, you can set up a cluster of WebSphere Commerce instances. In addition, having a federated environment enables you to manage multiple WebSphere Commerce application servers from a single WebSphere Application Server console.

Any combination of production, staging, or authoring servers can be federated on condition that their instance names are unique.

Before you begin

In a federated WebSphere Commerce environment, you can complete the following:

Use a single WebSphere Application Server console to administer multiple WebSphere Commerce instances
Set up a cluster of WebSphere Commerce instances

An existing WebSphere Commerce instance is required for this task.

If you create extra WebSphere Commerce instances after you complete this federation process, you can manually add any new instance to the deployment manager profile by following the steps in this task. When a new WebSphere Commerce instance is created, the configuration manager does not automatically federate to the deployment manager profile.

Procedure

As a non-root user, install the WebSphere Application Server Network Deployment product using the media that are supplied with WebSphere Commerce. This node now hosts the deployment manager. Although you can install other application servers on the same node as the deployment manager, it is not done unless you have a node with the capacity to host both products.
Create a WebSphere Application Server Deployment Manager profile on the WebSphere Application Server Network Deployment machine. For more information about creating a WebSphere Application Server Deployment Manager profile, see:
- Create a Deployment Manager profile using the WebSphere Application Server Profile Manager
- Creating a WebSphere Application Server Deployment Manager profile
On the WebSphere Application Server Network Deployment machine, start the deployment manager server.
- Start the Deployment Manager
- Start the Deployment Manager
Create the WebSphere Application Server non-root user and group if they do not exist on the WebSphere Commerce node.
Increase the maximum heap size for the Java processes involved.
1. Identify the maximum stack that is allowed for your system.
  This value that you specify depends on the following factors:
  - The JVM type (32-bit versus 64-bit)
  - The amount of physical memory available
  - The other processes that run on the system, including other JVMs
  If you are unsure of the value to specify, choose 1024M.
  In the following steps, the max_allowed variable is the maximum stack value.
2. Increase the maximum heap size for the JVM created by the addNode script:
  - Perform the following steps:
    - Log on to the WebSphere Commerce node as root.
    - Open the WAS_installdir/bin/addNode.sh file in a text editor.
    - In the text file, find the following line of text:
      "$JAVA_HOME"/bin/java \
    - Insert the following parameter below the "$JAVA_HOME"/bin/java \ line of text:
      -Xms256m -Xmxmax_allowed \
      For example, one of the following lines can be inserted:
      
      -Xms256m -Xmx1024m \ indicates that the max_allowed is set to 1024m
      
      -Xms256m -Xmx12288k \ indicates that the max_allowed is set to 12288k
      
      The max_allowed parameter represents the Java maximum heap size value that is allowed by your operating system. This value must a multiple of 1024. Append the letter k or K to indicate kilobytes, or m or M to indicate megabytes.
    - Save the changes and exit the text editor.
  - Perform the following steps:
    - Open the WAS_installdir/bin/addNode.bat file in a text editor.
    - In the text file, find the following line of text:
      "%JAVA_HOME%\bin\java" -Dcmd.properties.file=%TMPJAVAPROPFILE% %WAS_DEBUG% %WAS_TRACE% %CONSOLE_ENCODING% "%CLIENTSOAP%" "%JAASSOAP%" "%CLIENTSAS%" "%CLIENTSSL%" %USER_INSTALL_PROP% "-Dwas.install.root=%WAS_HOME%" "-DWAS_HOME=%WAS_HOME%" -Xms256m -Xmx1024m "com.ibm.wsspi.bootstrap.WSPreLauncher" -nosplash -application "com.ibm.ws.bootstrap.WSLauncher" "com.ibm.ws.admin.services.NodeFederationUtility" "%CONFIG_ROOT%" "%WAS_CELL%" "%WAS_NODE%" %*
    - Insert the following parameters between the "-DWAS_HOME=%WAS_HOME%" and "com.ibm.ws.bootstrap.WSLauncher" entries:
      -Xms256m -Xmxmax_allowed
      For example, one of the following lines can be inserted:
      
      -Xms256m -Xmx1024m indicates that the max_allowed is set to 1024m
      
      -Xms256m -Xmx12288k indicates that the max_allowed is set to 12288k
      
      The max_allowed parameter represents the Java maximum heap size value that is allowed by your operating system. This value must a multiple of 1024. Append the letter k or K to indicate kilobytes, or m or M to indicate megabytes.
    - Save the changes and exit the text editor.
3. Increase the maximum heap size for the administration server JVM:
  1. Log on to the WebSphere Application Server Network Deployment manager administrative console.
  2. Expand System Administration > Deployment Manager > Java and Process Management > Process Definition > Java Virtual Machine.
  3. Change the Maximum Heap Size value to the maximum value supported by your operating system. For example, 1024 MB. You can reduce this number after you complete the federation process.
  4. Restart the Deployment Manager.
Before you federate the WebSphere Commerce application server node into the deployment manager cell, set the SOAP connection timeout to 0. To adjust the SOAP timeout setting, complete the following steps on the WebSphere Commerce node:
1. Open the following file in a text editor:
```
WC_profiledir/properties/soap.client.props
```
2. Search for the com.ibm.SOAP.requestTimeout entry. Record the existing value, and change the value to 0.
  For example, com.ibm.SOAP.requestTimeout=0.
3. Save the file, and exit.
Ensure that the system clocks on your WebSphere Commerce node and your WebSphere Application Server Network Deployment node are synchronized within 5 minutes of each other and are set to the same time zone. If they are not, federation fails.
On the WebSphere Commerce node:
1. Log on as the non-root user.
2. Start a Qshell session by typing QSH in the IBM i command prompt.
3. Federate the WebSphere Commerce application server into the deployment manager cell by issuing the addNode command, as shown in the following examples:
  - WC_profiledir/bin/addNode.sh deployment_manager_host_name SOAP_port -includeapps [-username uid] [-password pwd] [-localusername localuid] [-localpassword localpwd]
  - WC_profiledir/bin/addNode deployment_manager_host_name SOAP_port -includeapps [-username uid] [-password pwd] [-localusername localuid] [-localpassword localpwd]
  - WC_profiledir/bin/addNode.bat deployment_manager_host_name SOAP_port -includeapps [-username uid] [-password pwd] [-localusername localuid] [-localpassword localpwd]
  Note: Your WebSphere Commerce instance is stopped automatically during the federation process. The command is shown on multiple lines for display purposes only; enter the command on one line.
  
  The variables and parameters in the command are defined as follows:
  
  WC_profiledir
  
  This directory is created for the WebSphere Application Server profile that is used by a WebSphere Commerce instance.
  
  deployment_manager_host_name
  
  The fully qualified host name of the deployment manager node.
  
  SOAP_port
  
  The SOAP port on which the deployment manager listens. This port number is defined when you create the deployment manager profile. The default deployment manager port is 8879.
  
  includeapps
  
  When you federate a WebSphere Commerce profile that contains a WebSphere Commerce instance, you must include this parameter to ensure that the WebSphere Commerce application (EAR) file is transferred to the new configuration.
  
  username
  
  If security is enabled, specify the user name for authentication. Acts the same as the -user option. The user name that you choose must be a pre-existing user name.
  
  password
  
  If security is enabled, specify the password for authentication. The password that you choose must be one that is associated with a pre-existing user name.
  
  localusername
  
  Specify the user name for authentication for existing application servers on the node that you want to federate. This parameter is only applicable if security is enabled for the application server.
  
  localpassword
  
  Specify the password for authentication for existing application servers on the node that you want to federate. The password that you choose must be one that is associated with a pre-existing user name. This parameter is only applicable if security is enabled for the application server.
  
  For more information about the addNode command, see addNode command.
Note: After you federate a WebSphere Application Server profile, the node agent must be managed by the non-root user. For more information, see Using a non-root user to run an application server and node agent.
You must reset the SOAP connection timeout to the original value. To adjust the SOAP timeout setting, complete the following steps on the WebSphere Commerce node:
1. Open the following file in a text editor:
```
WC_profiledir/properties/soap.client.props
```
2. Search for the com.ibm.SOAP.requestTimeout entry. Reset the entry to the original value. For more information, see the following topics:
  - WebSphere Application Server Best Practices
  - WebSphere Application Server Best Practices
3. Save the file, and exit.
If you are federating a profile that contains a WebSphere Commerce instance, you must re-create the cell level documents, such as a remote web server, on your WebSphere Commerce node. To re-create these documents, complete the following steps on the WebSphere Commerce node:
Note:
- This step is not required if you are adding a WebSphere Application Server node that does not contain a WebSphere Commerce instance.
- If both staging and production are federated into one DMGR, you must check that their modules are properly mapped after the reconfigure cell command is run. Ensure that the modules in staging are mapped to webserver1 for staging, and the modules in production are mapped to webserver1 for production.
1. Open the WC_installdir/instances/instance_name/xml/instance_name.xml file.
2. Update the AdminUser and AdminPwd parameters with the DMGR username and password.
  For example:
```
<Security AES_DB="false" AES_Files="false"
	AdminPwd="password" AdminUser="dmgr"
	AuthMode="" Realm="" RunAsID="" RunAsPwd="" enabled="false"
	enabledGlobal="true" passwordpolicy="true"/>
```
3. Switch to the WebSphere Commerce non-root user by running the following command in a terminal window: su - WC_non_root_user
4. Start a Qshell session by typing QSH in the IBM i command prompt.
5. Run the following command:
```
WC_installdir/bin/config_ant.sh -DinstanceName=instance_name ReconfigureCell
```
```
WC_installdir/bin/config_ant.sh -DinstanceName=instance_name ReconfigureCell
```
```
WC_installdir/bin/config_ant.bat -DinstanceName=instance_name ReconfigureCell
```
  Note: If the following error displays, the system cannot find the configuration file:
```
java.io.IOException: java.io.IOException
```
  To resolve this problem, see config_ant fails when federating WebSphere Commerce on Windows
If you enabled security before you federated your WebSphere Commerce application, you must enable security again. This step is necessary because the cell-level configuration information for your previous stand-alone WebSphere Commerce server is either replaced or superseded by the cell-level configuration of the deployment manager cell.

Note: If you previously enabled security with federated repositories, then you must delete the following files before you re-enable security. On your WebSphere Commerce application, check whether file names like the following example exist: WC_installdir/instances/instance/properties/version/ldap*.component If they do, then delete those files.

Complete the steps to enable global security.
If you enabled automatic propagation of the web server configuration file (plugin-cfg.xml) before federating, you must configure it again.
Regenerate the web server plug-in for your web server.
1. Log on the WebSphere Application Server Network Deployment Administration Console server.
2. Expand Servers > Server Types > Web servers.
3. Select webserver1 and click Generate Plug-in to generate the plugin-cfg.xml file for the web server.
Copy the updated plugin-cfg.xml file to your web server:
- Communicating with web servers
- Communicating with web servers
Update the path to the plugin-cfg.xml file in the web server configuration file on the web server.
Restart your web server.

Results

After you federate the WebSphere Commerce application server nodes into a deployment manager cell, you can start and stop WebSphere Commerce by following the instructions in:

What to do next

Important: You must change the execution properties to complete the federation process.