+

Search Tips   |   Advanced Search

Migrate an HCL WebSphere Portal stand-alone server to IBM WAS 9.0.5

We can migrate the HCL WebSphere Portal profile to WebSphere Application Server 9.0.5.15. Two options exist for this migration process: local or remote.

Ensure that you migrate your Search Collection before migrating the HCL Portal server.

Note:

For the purposes of these instructions, the following terms are used:

  1. For a local migration only: Install WebSphere Application Server 9.0.5. For a remote migration only: Install HCL WebSphere Portal 9.5 on the remote target server. During installation on the target system, use the same WebSphere Application Server, Portal Server, and wp_profile directory paths as the source server.
  2. Create a base profile on the target WebSphere Application Server 9.0.5.15 using the manageprofiles command line option.

    Important:

    • The WebSphere Application Server 9.0.5.15 migration is different from the standard HCL WebSphere Portal migration in that references in the source environment are updated to point to the target WebSphere Application Server 9.0.5.15 environment.

    • Use the exact same cell name, and node name usedd for the HCL WebSphere Portal 9.5 and WebSphere Application Server 9.0.5.15 installation.

    • AIX : ./manageprofiles.sh -create -defaultPorts -enableAdminSecurity false -profileName -profilePath -templatePath /profileTemplates/default -nodeName source_node -cellName source_cell_name -hostName host_name -isDefault -omitAction samplesInstallAndConfig defaultAppDeployAndConfig
    • Linux : ./manageprofiles.sh -create -defaultPorts -enableAdminSecurity false -profileName -profilePath -templatePath /profileTemplates/default -nodeName source_node -cellName source_cell_name -hostName host_name -isDefault -omitAction samplesInstallAndConfig defaultAppDeployAndConfig
    • Windows : manageprofiles.bat -create -defaultPorts -enableAdminSecurity false -profileName -profilePath -templatePath /profileTemplates/default -nodeName source_node -cellName source_cell_name -hostName host_name -isDefault -omitAction samplesInstallAndConfig defaultAppDeployAndConfig

    Where the following values are set:

      source_node

      The node name on the source installation.

      source_cell_name

      The cell name on the source installation.

      host_name

      The host name of the environment.

  3. Open a command prompt.

    Note: If we are instructed to open a properties file, they are ASCII files. Open them with the appropriate tool.

  4. For a local migration only: Change to the source v85_wp_profile_path/ConfigEngine. Then, run the install-wp-migration-files task to install HCL Digital Experience-specific files into the WebSphere Application Server 9.0.5.15 installation:

    Note: Ensure that the file folder that contains the source binary files is read/write enabled. If the folder is read only, the install-wp-migration-files task fails.

    • AIX : ./ConfigEngine.sh install-wp-migration-files -DNewWasLocation= -DWasPassword=password
    • Linux : ./ConfigEngine.sh install-wp-migration-files -DNewWasLocation= -DWasPassword=password
    • Windows : ConfigEngine.bat install-wp-migration-files -DNewWasLocation= -DWasPassword=password

    Note:

    • If this step fails, ConfigEngine might not be working. To fix this error, restore the ConfigEngine.migration.bak file that was created in the ConfigEngine root directory. Change ConfigEngine.migration.bak to ConfigEngine.sh or ConfigEngine.bat, depending on the operating system.

      Note: If ConfigEngine.migration.bak was not created, the failure occurred before the file was changed. Therefore, ConfigEngine should work.

    • For IBM i, the following error can be ignored: ConfigEngine.sh: 001-0050 Syntax error on line 252: token "fi" not expected.

  5. Ensure that the OSGi cache was cleared from the new WebSphere Application Server 9.0 installation by running the following command from the /bin directory:

      ./osgiCfgInit.sh -all

  6. For a remote migration only: On the HCL WebSphere Portal 9.0 server, create the PORTAL_V8.5.0.0_WAS_V90_OS.arch_RemoteMigrSupport.jar file. For example, the file might be PORTAL_V8.5.0.0_WAS_V90_windows.x86_RemoteMigrSupport.jar.

      cd PortalServer_root/bin ./genRemMigPkg.sh
      remote_zip_dir

    Where remote_zip_dir is an existing directory used to contain the generated file. Make sure specified the full path to the directory. Copy the PORTAL_V8.5.0.0_WAS_V90_OS.arch_RemoteMigrSupport.jar file from the HCL WebSphere Portal target server to the HCL WebSphere Portal source server. Extract the JAR file into a working directory. For example, extract PORTAL_V8.5.0.0_WAS_V90_linux.amd64_RemoteMigrSupport.jar. Linux only: Ensure that read and run permissions are set on the extracted files. For example: run chmod -R 755 supp_dir.

  7. On the source HCL WebSphere Portal server, complete the following steps to prepare the HCL WebSphere Portal profile for the WASPreUpgrade command.

    1. Uninstall any unnecessary applications.
    2. Delete backup and uninstalled applications.
    3. Delete any old large log files or temp files that are no longer needed, which might require the HCL WebSphere Portal Server to be stopped. The following locations are for common temp files:

      • /temp/
      • /wstemp/
      • /config/temp/

  8. The WASPreUpgrade and WASPostUpgrade commands that are used in HCL WebSphere Portal migration use much memory and might result in an OutOfMemoryException. To prevent this error from happening:

    1. Ensure that we are using a large enough heap size. Generally, using 2 GB heap size is sufficient, specified using the -javaoption -Xmx2048m variable when we run WASPreUpgrade or WASPostUpgrade commands. Increase the heap size by increasing the -Xmx2048m variable. A possible value might be -Xmx4096m.

    2. Ensure that the size of the HCL WebSphere Portal profile was minimized by deleting unnecessary files. In most cases, the HCL WebSphere Portal profile (wp_profile) should not be larger than 2 GB. Search for files larger than 10 MB to find any possible files that can be contributing to a large profile size. For example:

      • In Linux we can use the following command to find files larger than 10 MB: > find . -type f -size +10000k -exec ls -lh {} \; | awk '{ print $9 ": " $5 }'.

      • In Windows , we can run the following search in Windows Explorer: *.* size:> 10MB

  9. Stop HCL WebSphere Portal before running the WASPreUpgrade command.
  10. Set the file descriptor limit to at least 20480. 

      ulimit -n 20480
  11. Set the stack limit to at least 65536. 

      ulimit -s 65536
  12. AIX only: Use the following steps to increase the maximum length of the command line with environment variables:

    1. Run the following command to query the system attributes: 

        lsattr -EH -l sys0 | grep ncargs
      The command returns a value similar to the following example: 

        ncargs  256  ARG/ENV list size in 4K byte blocks  True
    2. If the ncargs value is less than 512, run the following command to increase the value: 

        chdev -l sys0 -a ncargs=1024
  13. For a local migration only : Run the WASPreUpgrade command from the /bin directory. For a remote migration only : Run the WASPreUpgrade command from the working_directory/bin directory that contains the remote migration package that is copied earlier. Add the extra parameter -machineChange true.

    • AIX : ./WASPreUpgrade.sh temp_dir -javaoption -Xmx2048m -oldProfile -username was_admin_user -password was_admin_user_pswrd
    • Linux : ./WASPreUpgrade.sh temp_dir -javaoption -Xmx2048m -oldProfile -username was_admin_user -password was_admin_user_pswrd
    • Windows : WASPreUpgrade.bat temp_dir -javaoption -Xmx2048m -oldProfile -username was_admin_user -password was_admin_user_pswrd

    Where the following values are set:

      temp_dir

      Temporary directory where the backup is stored.

    Note:

    • If we are running this command on Windows , the temp_dir cannot have spaces in the path.

    For example, your command might look like: ./WASPreUpgrade.sh /opt/HCL/wasMigrateBackup /opt/HCL/WebSphere/AppServer -javaoption -Xmx2048m -oldProfile -username was_admin_user -password was_admin_user_pswrd

  14. For a remote migration only : Compress and copy the backup that is created by the WASPreUpgrade command from the source server to the remote target server. Extract the backup into a temporary directory such as temp_dir.
  15. For a local migration only : Run the WASPostUpgrade command from the /bin directory on the local server. For a remote migration only: Run the WASPostUpgrade command from the /bin directory on the remote target server. The WasPostUpgrade command migrates the backed-up source profile into the new profile.

    Note: If security is enabled on our profile, add the -username was_userid -password was_userid_password parameters to your WASPostUpgrade task.

    • AIX : ./WASPostUpgrade.sh temp_dir -profileName -oldProfile -javaoption -Xmx2048m
    • Linux : ./WASPostUpgrade.sh temp_dir -profileName -oldProfile -javaoption -Xmx2048m
    • Windows : WASPostUpgrade.bat temp_dir -profileName -oldProfile -javaoption -Xmx2048m

    For example, your command might look like: ./WASPostUpgrade.sh /opt/IBM/wasMigratedBackup -profileName wp_profile -oldProfile wp_profile -javaoption -Xmx2048m.

    If the WASPreUpgrade was successful, but the WASPostUpgrade command results in an error, complete the following steps:

    1. Check that only one profile exists in the backup profile.
    2. If necessary, delete the search collection to decrease the data size.
    3. Move JCR Data during migration.

      Note: The Java Content Repository might store index-related files in subdirectories in the WebSphere profile, such as jcr, that can use much space. This data is not altered by the migration process, so it can be temporarily moved out of the old profile or the backup directory in preparation for migration. Move the directory into the new profile after migration completes.

    4. Ensure that no paths exist with the : character. The character might cause problems for WASPreUpgrade and WASPostUpgrade commands.
  16. If the source and target profile names are not the same, in the Source ConfigEngine path, run the action-copy-ce-script-native-encoding task:

    Note: The source ConfigEngine path should be in the same path as the PortalServer and AppServer paths. Do not run this task from the ConfigEngine path that is located within the source profile.

    • AIX : ./ConfigEngine.sh -profileName action-copy-ce-script-native-encoding -DWasPassword=password -DPortalAdminPwd=password
    • Linux : ./ConfigEngine.sh -profileName action-copy-ce-script-native-encoding -DWasPassword=password -DPortalAdminPwd=password
    • Windows : ConfigEngine.bat -profileName action-copy-ce-script-native-encoding -DWasPassword=password -DPortalAdminPwd=password

  17. Disable syndication and Portal search in the source environment.
  18. Create a copy of the HCL WebSphere Portal source database. Refer to the database documentation for instructions on how to create the backup.
  19. Modify wkplc_dbdomain.properties on the HCL WebSphere Portal target server to point to the database copy.

  20. Modify the following properties files so that the parameters point to the new / directory locations:

    1. From the /ConfigEngine/properties directory:

      • Verify that the DbLibrary parameter in wkplc_dbtype.properties points to the correct JDBC driver class. The value is either .zip or .jar. For example: /derby/lib/derby.jar.

      • Verify that the WpsInstallLocation parameter in the wkplc.properties file points to the installation location of HCL WebSphere Portal. For example: the value might be the /opt/HCL/PortalServer directory.

      • Verify that the administrative passwords in the wkplc_dbdomain.properties file were not deleted by the fix pack.

      • Verify that the WasRemoteHostName, WasSoapPort, WpsHostName properties in the wkplc.properties are set to the correct values.

    2. For a local migration only : From the /PortalServer directory, modify the following parameters in the wps.properties file:

      • WasRootDir=/
      • ProfileDirectory=

  21. cd to the /ConfigEngine directory.

  22. Run the following command:

    • AIX : ./ConfigEngine.sh validate-database -DWasPassword=password -DPortalAdminPwd=password
    • Linux : ./ConfigEngine.sh validate-database -DWasPassword=password -DPortalAdminPwd=password
    • Windows : ConfigEngine.bat validate-database -DWasPassword=password -DPortalAdminPwd=password

  23. Run the following command to re-create your data sources:

    • AIX : ./ConfigEngine.sh connect-database -DWasPassword=password -DPortalAdminPwd=password
    • Linux : ./ConfigEngine.sh connect-database -DWasPassword=password -DPortalAdminPwd=password
    • Windows : ConfigEngine.bat connect-database -DWasPassword=password -DPortalAdminPwd=password

  24. Run the following post-was-migration-update command:

    • AIX : ./ConfigEngine.sh post-was-migration-update -DWasPassword=password -DPortalAdminPwd=password -DoldProfileLocation=v85_wp_profile_path
    • Linux : ./ConfigEngine.sh post-was-migration-update -DWasPassword=password -DPortalAdminPwd=password -DoldProfileLocation=v85_wp_profile_path
    • Windows : ConfigEngine.bat post-was-migration-update -DWasPassword=password -DPortalAdminPwd=password -DoldProfileLocation=v85_wp_profile_path

  25. Start the HCL WebSphere Portal server.

    Note: If the WebSphere Application Server migration fails:

    • Refer to the job log in the WebSphere Application Server temporary directory to troubleshoot WebSphere Application Server migration errors.
    • Rerun the install-wp-migration-files command from step 3.

  26. After migrating our profile to WebSphere Application Server 9.0.5.15, the Configuration Wizard in the v85_AppServer root/profiles/cw_profile directory is still usable. To have the wizard also running on WebSphere Application Server 9.0.5, cd /ConfigEngine.

    • AIX : ./ConfigEngine.sh create-config-wizard -DWizardUserid=userID -DWizardPassword=password -DWasPassword=password
    • Linux : ./ConfigEngine.sh create-config-wizard -DWizardUserid=userID -DWizardPassword=password -DWasPassword=password
    • Windows : ConfigEngine.bat create-config-wizard -DWizardUserid=userID -DWizardPassword=password -DWasPassword=password

Parent topic: Install HCL WebSphere Portal