Migrating CLM to a New Environment

Introduction

This section will outline the process of migrating a CLM environment to a new one. It does not provide step-by-step instructions on configuring deployments, but that information can be found in the product documentation (CLM Information Center) linked in the References Section.

Reasons Why You May Want to Move the Installation

• To more robust hardware
• To change the operating system
• To a drive with more space
• From an image system to a physical machine or vice-versa

First Consideration is the Public URL

When you first installed CLM, you should have chosen a public URI that is fully qualified and accessible from anywhere in the network where users need to connect. That URI should have been based on a stable host name that was rerouted through a domain name server (DNS). It should be decoupled from the host names of the existing servers. If this is not the case, you may have to consider going through a server rename after the migration. You will also want to consider how you can restrict access to the systems while migrating. If the source environment is going to be removed from the network or de-commissioned after the migration, you may not need the server rename.

This process is going to assume you have well-planned public URIs per the product documentation.

Server Timezone

For releases prior to 6.0.5, you cannot move applications to a server running in a different timezone. Starting with 6.0.5, you can change the timezone setting of an existing server (or migrate to a server in a different timezone). If you are both upgrading from a pre-6.0.5 release and migrating to a new environment, you should do the upgrade to 6.0.5 (or later) first. Otherwise, see the section below on migrating configuration files for manual edits that must be applied.

Summary of Migration

The steps for a migration are a combination of the following operations listed below:

1. Backup/recovery

Before beginning any type of migration operation, you should ensure that you have tested procedures to backup and restore your environment.

2. New Installation

You will need to perform many of the installation steps on the target system as if you were creating a new one.

3. Upgrade

This procedure is only for migrating an environment, meaning move an environment from one (the source) to another (the target), and not for an upgrade (change of software version). However, since a CLM upgrade is a side-by-side upgrade and not an in-place upgrade, the steps and the commands in the upgrade scripts which copy specific configuration files from the JAZZ_HOME environment to the target system are the same for a migration. You can still use much of the interactive upgrade guide to help document the migration plan.

You should already be very familiar with the first two operations. If you are familiar with upgrading a CLM environment already, then you understand most of what is needed to migrate to a new environment.

Steps to Migrate

1. Preparation

• Review the steps below and the corresponding product documentation.
• Assemble documentation for any customizations you made to the start up scripts, WAS profiles, etc.
• Create a test environment to test out the migration.
• Plan the backup and downtime for the migration.
• Create procedure to disable access to the source environment.

2. Installation

Follow the installation instructions in the product documentation under the topic "Installing the Rational solution for Collaborative Lifecycle Management (CLM)" for these subtopics:

• Hardware and software requirements
• Installing the CLM software (Jazz Team Server and applications). Do not run setup.
• Installing the database: You do not need to set up the database but you do need to configure the target environment for using the existing CLM databases. This will include installing the database driver and setting environment variables.
• Deploying and configuring the application server including the user registry:

For Tomcat: the application server will get installed with the CLM software.

For Web Sphere: follow the instructions to install and configure the server including the user registry. Make any adjustments to the settings that you had customized in the source environment.

3. Shut down the source system

Disable access to the source environment from the network.

Shut down and backup the source environment.

4. Migrate existing configuration files

Copy the existing configuration files from the source (old_install_dir) to the target (new_install_dir) environment. Include the following:

• Database files if vendor is Derby:

  cp -R old_install_dir/server/conf/jts/derby/repositoryDB  new_install_dir/server/conf/jts/derby
  cp -R old_install_dir/server/conf/ccm/derby/repositoryDB new_install_dir/server/conf/ccm/derby
  cp -R old_install_dir/server/conf/qm/derby/repositoryDB  new_install_dir/server/conf/qm/derby

  and similarly for any other applications that have Derby databases

• Application Server if Tomcat: Copy/replace the configuration and user registry files and any files you may have customized (e.g. server.startup.bat). Note: if you are migrating across operating systems, best practice is to use the installed configuration files and add your customizations manually:

  server-install-dir/server/tomcat/conf/server.xml
  server-install-dir/server/tomcat/conf/web.xml

• For LDAP:

  server-install-dir/server/tomcat/webapps/APP/WEB-INF/web.xml where APP is jts, ccm, qm

• For Tomcat user registry:

  server-install-dir/server/tomcat/conf/tomcat-users.xml

• Application configuration files:

  cp old_install_dir/server/conf/admin/admin.properties new_install_dir/server/conf/admin/admin.properties

• Repeat for these files:

  old_install_dir/server/conf/admin/friends.rdf        
  old_install_dir/server/conf/ccm/teamserver.properties 
  old_install_dir/server/conf/qm/teamserver.properties  
  old_install_dir/server/conf/jts/teamserver.properties 
  old_install_dir/server/conf/rm/friendsconfig.rdf      
  old_install_dir/server/conf/rm/fronting.properties

If you are migrating to a server running in a different timezone, then you must upgrade to version 6.0.5 or later. It is recommended to do the server upgrade first, but if the move is done first, then this property should be added to every teamserver.properties file after it is copied to the new server:

com.ibm.team.repository.db.timezone=<old timezone>

where <old timezone> is replaced by the timezone identifier for the timezone that was used by the old server (such as "America/New_York" for U. S. Eastern time, for example).

If a data warehouse database is being used, then this property should also be added to teamserver.properties as well:

com.ibm.team.datawarehouse.db.timezone=<old timezone>

Note that the property is only recognized in CLM 6.0.3, 6.0.4, 6.0.5, and 6.0.6 fixpacks (and subsequent releases) released after August 2018. If using an older version, the data warehouse database must be completely regenerated in order to avoid issues when changing a server's timezone.

5. Copy or Rebuild Indexes

The index files are referenced in the teamserver.properties file with relative path locations (e.g. com.ibm.team.fulltext.indexLocation=conf/qm/indices/workitemindex, com.ibm.team.jfs.index.root.directory=indices). So these entries should not have to change when you create new install areas. But after a new installation, the index files under these directories would not match. So you must copy these files from the source to the target. If the operating systems are different, you should rebuild the indexes with repotools commands. This will take longer and must be done with the database running and the server shut down.

Post Migration

1. Ensure the clocks for the server and database are in sync.

2. Ensure the JAZZ_HOME environment variable is set.

3. Start the server.

4. Log in as a user with jazzadmins and import the licenses.

5. Smoke test.

6. Enable network access to the new server.

References for Detailed Instructions

Interactive Upgrade and Installation Guides available in the product documentation

https://jazz.net/help-dev/clm/index.jsp

https://jazz.net/wiki/bin/view/Deployment/BackupCLM

http://pic.dhe.ibm.com/infocenter/clmhelp/v3r0m1/index.jsp?topic=%2Fcom.ibm.jazz.install.doc%2Ftopics%2Ft_upgrading_3011.html

Related topics: Deployment web home, Deployment web home

External links:

• IBM

Additional contributors: TWikiUser, TWikiUser