Migrating an HCL Portal stand-alone server to IBM WAS 9.0.5
You can migrate your HCL Portal profile to WebSphere Application Server 9.0.5. Two options exist for this migration process: local or remote.
Before you begin
- For a local migration only: Install the latest WebSphere Application Server version on the same server where HCL Portal 9.0 is installed.
- For a remote migration only: Install HCL Portal 9.0 with the latest WebSphere Application Server on a separate server, which will be the target server for the migration. In both scenarios, make a copy of the source database to use on the target server. 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
- v85_wp_profile_name
- This term refers to the original HCL Portal profile on the WebSphere Application Server 8.5.5.5 or higher installation.
- v90_wp_profile_name
- This term refers to the new HCL Portal profile on the WebSphere Application Server 9.0 installation.
- v85_wp_profile_path
- This term refers to the full path to the HCL Portal 8.5 profile.
- v90_wp_profile_path
- This term refers to the full path to the HCL Portal 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
- 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. During installation on the target system, use the same WebSphere Application Server, Portal Server, and wp_profile directory paths as the source 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 exact same cell name, and node name that you used for the HCL Portal 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
Where the following values are set:- 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 Digital
Experience-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.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
.
- 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
- AIX®:
-
For a remote migration only: On the HCL Portal 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: runchmod -R 755 supp_dir
. - AIX®:
-
On the source HCL Portal server, complete the following steps to prepare the HCL Digital Experience profile for
the WASPreUpgrade command.
-
The WASPreUpgrade and WASPostUpgrade commands that are
used in HCL Portal migration use much memory and might result in an
OutOfMemoryException. To prevent this error from happening, complete the
following steps:
- Stop HCL Portal 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:
-
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 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
- AIX®:
-
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 theWASPostUpgrade
command from the /bin directory on the remote target server. TheWasPostUpgrade
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:
- AIX®:
-
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
- AIX®:
- Disable syndication and Portal search in your source environment.
- Create a copy of the HCL Digital Experience source database. Refer to your database documentation for instructions on how to create the backup.
- Modify the wkplc_dbdomain.properties file on the HCL Portal target server to point to the database copy.
-
Modify the following properties files so that the parameters point to the new
/ directory locations:
- 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
- AIX®:
-
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
- AIX®:
-
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
- AIX®:
-
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
- AIX®: