Upgrading to a fully distributed enterprise topology

You can upgrade your installation of Rational Team Concert™ to v3.0.1 with new, but distributed, CCM and JTS applications using the procedure described in this topic.

Before you begin

Important: Ensure that the clocks on all machines are synchronized using the Network Time Protocol (NTP). Time is the critical element that allows an event on one network node to be mapped to a corresponding event on another. To avoid problems, these challenges can be overcome by the enterprise deployment of the NTP service. For more information about NTP, visit http://www.ntp.org/.
Note: The examples here are for Jazz Team Server and Change and Configuration Management. You can use the same procedure for Quality Management application.

Review the Fully distributed Rational Team Concert 2.0 to 3.0.1 enterprise topology example topic for an example of the Fully distributed Rational Team Concert 3.0.1 enterprise topology.

When distributing the JTS application to a separate server, ensure the second server you are deploying the JTS to has the same operating system and application server configuration. Using the same operating system and application server will make the migration of files less complicated.

Ensure that both servers use the same authentication method and user realm for their users.

Review and consider Deploying with single sign-on. If you are using WebSphere, this will facilitate authentication in a multi-server environment.

At the end of v3.0.1 installations under "Which program do you want to start" select None. You must run the JTS setup wizard only after the migration of files and repositories are complete.

Preparing configuration files

Procedure

  1. On Machine A (the one with the RTC 2.x server to be upgraded), install the v3.0.1 Change and Configuration Management application without Jazz Team Server (JTS) and without the RTC trial licenses.
    Note: Ensure that in the context root panel you are selecting Use Rational Team Concert 2.x context root.
  2. On Machine B, install the v3.0.1 Jazz Team Server (JTS) application and the RTC trial licenses without Change and Configuration Management on the server that will become the shared JTS.
    Note: Ensure that in the context root panel you are selecting Use Rational Team Concert 2.x context root.
  3. On Machine A, open a new command window and navigate to 3.0.1_install_dir/server.
  4. Run the following command to merge the Jazz and Tomcat configuration files:
    repotools-jazz -migration_ccm_updateConfigurationFiles oldJazzHome=2.x_install_dir/server/conf
    Note: By default, the -migration_ccm_updateConfigurationFiles command updates both Jazz and Tomcat configuration files. If Tomcat is not installed and you want to update only the Jazz configuration files, you must specify the updateType=JAZZ parameter.
    repotools-jazz -migration_ccm_updateConfigurationFiles oldJazzHome=2.x_install_dir/server/conf updateType=JAZZ
  5. On Machine A, go to 3.0.1_install_dir/server/conf/jazz and review the contents of the RTC teamserver.properties file. Pay special attention to the database connection and public URL entries and confirm they are correct for the hostname for Machine A.
    CAUTION:
    It is critical that you review the contents of the merged files, specifically the database connection and public URL entries in both jazz and JTS teamserver.properties files. The jazz (RTC/CCM) teamserver.properties is located on Machine A under 3.0.1_install_dir/server/conf/jazz, while the JTS teamserver.properties to be edited and moved is located on Machine A under 3.0.1_install_dir/server/jts-migration/conf/jts.

    It is important that both teamserver.properties files are edited and updated (if necessary) for the correct server hostname that they will reside on.

    For more information and examples of verification points, refer to steps 3-6 in Preparing configuration files under Upgrading Rational Team Concert.

  6. After editing the JTS teamserver.properties on Machine A, copy it to Machine B under 3.0.1_install_dir/server/conf/jts. Backup the existing teamserver.properties file before replacing it.
  7. If deploying on Tomcat, you need to copy 3.0.1_install_dir/tomcat/conf/tomcat-users.xml and 3.0.1_install_dir/tomcat/conf/server.xml files from Machine A to 3.0.1_install_dir/tomcat/conf folder on Machine B. Make backup copies of existing files before replacing them.
  8. If deploying on Tomcat and using LDAP, you will need to complete the following tasks to deploy the JTS with the edited web.xml file:
    1. On Machine B, start the JTS server using server.startup to extract the JTS.war file.
    2. On Machine B, stop the JTS server using the server.shutdown command.
    3. On Machine B, backup and then replace 3.0.1_install_dir/server/tomcat/webapps/jts/WEB-INF/web.xml with a copy of the equivalent web.xml file from Server A.

Results

This completes the configuration files migration.

Migrating the repository database

This section describes the steps required to do a repository database migration for a distributed JTS application.

Before you begin

Before proceeding with the repository database migration, verify that the following tasks have been completed:
  • A full, offline backup of the existing RTC 2.x database has been made.
  • Configuration files are migrated and are in place (teamserver.properties, friendsconfig.rdf, tomcat-users.xml, server.xml, web.xml). For more information, see Preparing configuration files.
  • The JTS repository database is created. For more information, see Setting up the database.
  • The Rational Team Concert v2.x server has been shut down.
  • If using Derby for the Rational Team Concert v2.x server, ensure the repository DB is copied from 2.x_install_dir/server/repositoryDB to the 3.0.1_install_dir/server directory.
  • For WebSphere Application Server migration:
    • Ensure that the RTC 2.x server has been shut down.
    • Stop and uninstall the jazz.war application.
    • Modify the JAZZ_HOME property to match the new installation path (3.0.1_install_dir/server/conf).
    • Modify the Oracle or SQL Server JDBC driver property if needed. See Setting up a WebSphere Application Server.
    • Optionally adjust the memory settings if needed. See Setting up a WebSphere Application Server.
    • Stop and restart the WebSphere Application Server.

Procedure

  1. On Machine A, open a command window and change to the 3.0.1_install_dir/server directory.
  2. Run the following command to add tables to the database:
    repotools-jazz -addTables
  3. Run the following command to export user information from the RTC database:
    repotools-jazz -migration_exportJTSData toFile=jtsData.tar
  4. On Machine A, copy the jtsData.jar file just created and put it on Machine B in the 3.0.1_install_dir/server directory.
  5. On Machine B, run the following command to import user information into the JTS database:
    Important: If you are not using the default Derby database, ensure that the JTS database referenced in the conf/jts/teamserver.properties was created and exists.
    repotools-jts -migration_importJTSData fromFile=jtsData.tar createMappingFile=rtc-mapping.txt createTables
  6. On Machine B, copy the rtc-mapping.txt file just created and put it on Machine A in the RTC3.0.1_install_dir/server directory.
  7. On Machine A, run the following command to import JTS user information into the RTC database:
    repotools-jazz -migration_importUserMapping fromMappingFile=rtc-mapping.txt

Post-migration repository tools commands

Procedure

On Machine A, run the following commands to rebuild indexes:

repotools-jazz -rebuildTextIndices

repotools-jazz -reindex

Results

This completes the repository database migration.

Post-migration setup

About this task

The post-migration steps for migrating a RTC server and distributing the JTS application are the same as the ones documented for migrating in a single server environment, except that you must also complete the following tasks:

Procedure

During the launch of the Jazz Team Server setup wizard, the CCM application will not be automatically recognized and pre-filled due to the distributed environment. If the CCM application is not automatically recognized during Jazz Team Server setup, see Step 9c in Running the setup wizard.

Feedback