Migrating an HCL Digital Experience stand-alone server to IBM WAS 9.0.5
You can migrate HCL Digital Experience (DX) profile to WebSphere Application Server 9.0.5 through local or remote migration process.
Before you begin
Make sure that you migrate your Search Collection before you migrate your HCL DX server: - For a local migration only: Install the latest WebSphere Application Server version on the same server where HCL DX 9.0 is installed.
-
For a remote migration only: Install HCL DX 9.0 with the latest WebSphere Application Server on a separate server, which is the target server for the migration. In both scenarios, make a copy of the source database to use on the target server.
Note
The remote migration is a better option because it leaves the source migration environment intact. For a local migration, the source migration profile is no longer usable after the migration.
About this task
The following terms are used for carrying out the instructions:
-
v85_wp_profile_name This term refers to the original HCL DX profile on the WebSphere Application Server 8.5.5.5 or higher installation.
-
v90_wp_profile_name
This term refers to the new HCL DX profile on the WebSphere Application Server 9.0 installation.
- v85_wp_profile_path
This term refers to the full path to the HCL DX 8.5 profile.
- v90_wp_profile_path
This term refers to the full path to the HCL DX 9.0 profile.
- v85_was_root_path
This term refers to the full path to the WebSphere Application Server 8.5.5.5 or higher installation.
- v90_was_root_path
This term refers to the full path to the WebSphere Application Server 9.0.5 or higher installation.
Procedure
-
During installation on the target system, use the same WebSphere Application Server, Portal Server, and wp_profile directory paths as the source server.
- For a local migration only: Install WebSphere Application Server 9.0.5.
- For a remote migration only: Install HCL Digital Experience 9.5 on the remote target server.
-
Create a base profile on the target WebSphere Application Server 9.0.5 by using the **manageprofiles command line option.
Important
The WebSphere Application Server 9.0.5 migration is different from the standard HCL Digital Experience migration in that references in the source environment are updated to point to the target WebSphere Application Server 9.0.5 environment. Use the same cell name, and node name that you used for the HCL DX 9.5 and WebSphere Application Server 9.0.5 installation.
-
AIX®:
./manageprofiles.sh -create -defaultPorts -enableAdminSecurity false -profileName -profilePath -templatePath /profileTemplates/default -nodeName source_node_name -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_name -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_name -cellName source_cell_name -hostName host_name -isDefault -omitAction samplesInstallAndConfig defaultAppDeployAndConfig
Set the following values:
-
source_node_name
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.
-
-
Open a command prompt.
Note
If you are instructed to open a properties file, they are ASCII files. Open them with the appropriate tool.
-
For a local migration only: Change to the source
v85_wp_profile_path/ConfigEngine
directory. Then, run the install-wp-migration-files task to install HCL DX specific files into the WebSphere Application Server 9.0.5 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 your operating system.
- 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
. - AIX®:
-
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:
-
AIX®:
./osgiCfgInit.sh -all
-
Linux™:
./osgiCfgInit.sh -all
-
Windows™:
osgiCfgInit.bat -all
-
-
For a remote migration only: On the HCL DX 9.0 server, run the following command to 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.-
AIX®:
cd PortalServer_root/bin ./genRemMigPkg.sh remote_zip_dir
-
Linux™:
cd PortalServer_root/bin ./genRemMigPkg.sh remote_zip_dir
-
Windows™:
cd PortalServer_root\bin genRemMigPkg.bat remote_zip_dir
Where
remote_zip_dir
is an existing directory that is used to contain the generated file. Make sure that you specify the full path to the directory. Copy the PORTAL_V8.5.0.0_WAS_V90_OS.arch_RemoteMigrSupport.jar file from the HCL Portal target server to the HCL 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
. -
-
On the source HCL DX server, complete the following steps to prepare the HCL DX profile for the WASPreUpgrade command.
- Uninstall any unnecessary applications.
- Delete backup and uninstalled applications.
- Delete any old large log files or temp files that are no longer needed, which requires the HCL DX Server to be stopped. The following locations are for common temp files:
- /temp/
- /wstemp/
- /config/temp/
-
The WASPreUpgrade and WASPostUpgrade commands that are used in HCL DX migration use much memory and might result in an OutOfMemoryException. To prevent this error from happening, complete the following steps:
-
Ensure that you are using a large heap size. Generally, using 2 GB heap size is sufficient, specified by using the
-javaoption -Xmx2048m
variable when you run WASPreUpgrade or WASPostUpgrade commands. Increase the heap size by increasing the -Xmx2048m variable. A possible value might be-Xmx4096m
. -
Ensure that the size of the HCL DX profile was minimized by deleting unnecessary files. In most cases, the HCL DX 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™, 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™, run the following search in Windows™ Explorer:
*.* size:> 10MB
- In Linux™, use the following command to find files larger than 10 MB:
-
-
Stop HCL DX before you run the WASPreUpgrade command.
-
Set the file descriptor limit to at least 20480.
ulimit -n 20480
-
Set the stack limit to at least 65536.
ulimit -s 65536
-
AIX only: Use the following steps to increase the maximum length of the command line with environment variables:
-
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
-
If the
ncargs
value is less than 512, run the following command to increase the value:chdev -l sys0 -a ncargs=1024
-
-
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
Set the following values:
temp_dir
Temporary directory where the backup is stored.
Note
If you 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
-
-
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.
-
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 your 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:
-
Check that only one profile exists in the backup profile.
-
If necessary, delete the search collection to decrease the data size.
-
Move Java™ Content Repository (JCR) Data during migration. !!! note The JCR might store index-related files in sub-directories 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.
-
Ensure that no paths exist with the ":" character. The character might cause problems for WASPreUpgrade and WASPostUpgrade commands.
-
-
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
-
-
Disable syndication and Portal search in your source environment.
-
Create a copy of the HCL DX source database. Refer to your database documentation for instructions on how to create the backup.
-
Modify the wkplc_dbdomain.properties file on the HCL DX target server to point to the database copy.
-
Modify the following properties files so that the parameters point to the new/directory locations:
-
From the /ConfigEngine/properties directory:
-
Verify that the DbLibrary parameter in the wkplc_dbtype.properties file 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 DX. 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.
-
-
For a local migration only: From the /PortalServer directory, modify the following parameters in the wps.properties file:
-
WasRootDir=/
-
ProfileDirectory=
-
-
-
Open a command prompt and change to the /ConfigEngine directory.
-
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
-
-
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`
-
-
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
-
-
Start the HCL 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.
-
After you migrate your profile to WebSphere Application Server 9.0.5, the Configuration Wizard in the v85_AppServer root/profiles/cw_profile directory is still usable. If you want to have the wizard also running on WebSphere® Application Server 9.0.5, run the following command from the /ConfigEngine directory:
-
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
-