Federating the WebSphere Commerce primary node

If you federate your WebSphere Commerce environment, you can set up a cluster of WebSphere Commerce instances. In addition, with a federated environment, you can 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

  1. As a non-root user, install the WebSphere Application Server Network Deployment product by using the media that are supplied with WebSphere Commerce. This node now hosts the deployment manager.
    Do not install other application servers on the same node as the deployment manager unless you have a node with the capacity to host both products.
  2. Verify the default WebSphere Application Server SDK level.
    1. Go to the WAS_installdir/bin folder.
    2. Run the following command.
      • LinuxAIX./managesdk.sh -getNewProfileDefault
      • Windowsmanagesdk.bat -getNewProfileDefault
      • For IBM i OS operating system
        1. managesdk -getNewProfileDefault
        2. managesdk -getCommandDefault
    3. If the default WebSphere Application Server SDK level is not 1.7, then run the following command to set to version 1.7.
      • LinuxAIX./managesdk.sh -setNewProfileDefault -sdkName 1.7_64
      • Windowsmanagesdk.bat -setNewProfileDefault -sdkName 1.7_64
      • For IBM i OS operating system
        1. managesdk -setNewProfileDefault -sdkname 1.7_64
        2. managesdk -setCommandDefault -sdkname 1.7_64
  3. 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
  4. On the WebSphere Application Server Network Deployment machine, start the deployment manager server.
  5. LinuxAIX Create the WebSphere Application Server non-root user and group if they do not exist on the WebSphere Commerce node.
  6. LinuxAIXWindowsIncrease the maximum heap size for the Java processes involved.
    1. Identify the maximum heap size 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
      Ensure that the maximum heap size is at least 1024m.

      In the following steps, the max_allowed variable is the maximum heap size.

    2. Increase the maximum heap size for the JVM created by the addNode script:
      • LinuxAIXPerform the following steps:
        1. Log on to the WebSphere Commerce node as root.
        2. Open the WAS_installdir/bin/addNode.sh file in a text editor.
        3. In the text file, find the following line of text: 
          MAX_HEAP_SIZE=

          The default value is MAX_HEAP_SIZE=-Xmx128m

        4. Increase the maximum heap size to at least 1024m:
          MAX_HEAP_SIZE=-Xmx1024m

          The maximum heap size represents the Java maximum heap size value that is allowed by your operating system. The minimum value is 1024m. This value must a multiple of 1024. Append the letter k or K to indicate kilobytes, or m or M to indicate megabytes.

        5. Save the changes and exit the text editor.
      • WindowsPerform the following steps:
        1. Open the WAS_installdir/bin/addNode.bat file in a text editor.
        2. 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%" "com.ibm.wsspi.bootstrap.WSPreLauncher" 
    -nosplash -application "com.ibm.ws.bootstrap.WSLauncher" "com.ibm.ws.admin.services.NodeFederationUtility" "%CONFIG_ROOT%" "%WAS_CELL%" "%WAS_NODE%" %*
        3. 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 maximum heap size represents the Java maximum heap size value that is allowed by your operating system. The minimum value is 1024m. This value must a multiple of 1024. Append the letter k or K to indicate kilobytes, or m or M to indicate megabytes.

        4. 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.
  7. Set the SOAP connection timeout to 0 before you federate the WebSphere Commerce application server node into the deployment manager cell.
    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.
  8. 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 the clocks are not synchronized, then federation fails.
  9. Federate WebSphere Commerce on the WebSphere Commerce node.
    1. LinuxAIX Log on as the non-root user.
    2. For IBM i OS operating system 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:
      • LinuxAIXWC_profiledir/bin/addNode.sh deployment_manager_host_name SOAP_port -includeapps [-username uid] [-password pwd] [-localusername localuid] [-localpassword localpwd]
      • For IBM i OS operating systemWC_profiledir/bin/addNode deployment_manager_host_name SOAP_port -includeapps [-username uid] [-password pwd] [-localusername localuid] [-localpassword localpwd]
      • WindowsWC_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.

    LinuxAIXNote: 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.
  10. 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 WebSphere Application Server Best Practices.
    3. Save the file, and exit.
  11. 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 needed 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. LinuxAIX Switch to the WebSphere Commerce non-root user by running the following command in a terminal window: su - WC_non_root_user
    3. For IBM i OS operating systemStart a Qshell session by typing QSH in the IBM i command prompt.
    4. Run the following command:
      LinuxAIX
      WC_installdir/bin/config_ant.sh -DinstanceName=instance_name ReconfigureCell
      For IBM i OS operating system
      WC_installdir/bin/config_ant.sh -DinstanceName=instance_name ReconfigureCell
      Windows
      WC_installdir/bin/config_ant.bat -DinstanceName=instance_name ReconfigureCell
      WindowsNote: 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
  12. 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.

  13. If you enabled automatic propagation of the web server configuration file (plugin-cfg.xml) before federating, you must configure it again.
  14. 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.
  15. Copy the updated plugin-cfg.xml file to your web server:
  16. Update the path to the plugin-cfg.xml file in the web server configuration file on the web server.
    If you are using IBM HTTP Server, update the path in the WC_installdir/instances/instance_name/httpconf/httpd.conf file.
  17. 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 procedure in:

What to do next

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