Moving a pilot or full production deployment using server rename

This topic describes the steps for renaming a small pilot or full production deployment.

Before you begin

Because LQE cannot be migrated automatically, it should be removed from the Jazz™ Team Server registered applications list and Jazz Team Server should be restarted before beginning the server rename process.

  1. Log in to the Administration page of the Jazz Team Server. Point your web browser to https://hostname:port/jts/admin.
  2. Click the Server tab.
  3. In the left pane, in the Configuration section, click Registered Applications.
  4. Remove the Lifecycle Query Engine as a registered application.
  5. Stop the Lifecycle Query Engine server.
  6. Restart the Jazz Team Server.
Note: After the rename, the source server(s) must be permanently taken out of service to avoid contamination of the production environment.

About this task

The server rename feature uses a mapping file to determine the URLs that should be renamed. A repotools command is provided to generate an initial mapping file for you. The mapping file contains source-target pairs for the Jazz Team Server and all applications, as well as any other URLs contributed by applications. See Mapping file for server rename for additional details about the mapping file.

Procedure

  1. Prepare and review the mapping file in advance of the actual rename while your servers are still online, following the steps described in the topic Preparing the mapping file.

    The end result of the preparatory phase is a mapping file that is generated on the source Jazz Team Server. The mapping file contains source-target pairs for the Jazz Team Server and all applications, as well as any other URLs contributed by applications.

  2. Back up the existing source environment and copy text indices and application configuration files to the new target installation. For distributed systems, go to the appropriate server to copy the files.
    Note: If you are performing a rename-in-place and not moving to new hardware, you are copying the environment from one installation to a second installation on the same system.
    1. Stop the Jazz Team Server and any distributed applications that are registered with the Jazz Team Server.

      In addition, stop any other applications that are affected by the server rename, or any affected, supported integrations.

      Note: While the server(s) are down, users will be unable to create or traverse links from any external systems that are integrated with the Rational® Engineering Lifecycle Manager deployment about to be renamed.
    2. Back up the databases for the source environment, including the Jazz Team Server database, the databases for the applications, the data warehouse database. If you are changing the database server or vendor, see Moving the database for additional steps.
    3. Copy the JFS/text indices from the source installation to the target installation.

      The following examples for a Linux server assume that the drives for the target production computers are network mounted. If this is not possible in your environment, use other file transfer methods to ensure that the files are copied.

      cp -R SourceJazzInstallDir/server/conf/jts/indices TargetJazzInstallDir/server/conf/jts 
      cp -R SourceJazzInstallDir/server/conf/relm/indices TargetJazzInstallDir/server/conf/relm 
    4. Copy the application configuration files from the source installation to the target production installation. As with the previous step, the examples below are for a Linux server and assume that the drives for the target production computers are network mounted.
      cp SourceJazzInstallDir/server/conf/jts/teamserver*.properties TargetJazzInstallDir/server/conf/jts 
      cp SourceJazzInstallDir/server/conf/relm/teamserver*.properties TargetJazzInstallDir/server/conf/relm 
      cp SourceJazzInstallDir/server/conf/admin/admin.properties* TargetJazzInstallDir/server/conf/admin
      cp SourceJazzInstallDir/server/conf/admin/friends.rdf* TargetJazzInstallDir/server/conf/admin 
    5. Copy the mapping file to the TargetJazzInstallDir\server directory on the target production server. See Preparing the mapping file for details about the mapping file.
  3. Perform the offline portion of server rename by importing the mapping file into the target production Jazz Team Server, using the repotools-jts -importURLMappings command.
    1. If you have an all-in-one deployment, import the mappings file using the repotools-jts -importURLMappings command as follows:
      • repotools-jts.bat -importURLMappings fromFile=".\mappings.txt"
      • ./repotools-jts.sh -importURLMappings fromFile="./mappings.txt"

      The rename will begin offline on the Jazz Team Server, before the server is restarted.

    2. If you have a distributed deployment and are allowed to map network drives, map a network drive from the Jazz Team Server host to each of the application hosts. Then, create a file (for example, serverConfFile.txt) that contains a list of the remote server/conf directories in your deployment in the following format:
       # Remote CCM server
         x:/JazzTeamServer/server/conf
         # Remote QM server
         y:/JazzTeamServer/server/conf
         # Remote RM server
         z:/JazzTeamServer/server/conf

      Finally, proceed with the repotools-jts -importURLMappings command and add the serverConfFile= parameter as shown below.

      • repotools-jts.bat -importURLMappings fromFile=".\mappings.txt" serverConfFile=".\serverConf.txt"
      • ./repotools-jts.sh -importURLMappings fromFile="./mappings.txt" serverConfFile="./serverConf.txt"
    3. If you have a distributed deployment and are not allowed to remap network drives, proceed with the repotools-jts -importURLMappings command (without the serverConfFile= parameter). Then, copy the server/conf/jts/.mappingEvent file to the remote application configuration directories (server/conf/application_name), that is, ccm, qm, and rm. The event file is generated when you import the mappings. You must copy the .mappingEvent file after you import the mapping file but before you start the server.

      The .mappingEvent file contains information that the applications need to contact the Jazz Team Server at its new location. The .mappingEvent file contents are the same for a given Jazz Team Server and its registered applications.

    Verify that the rename is successful by checking the console output and the JazzInstallDir/server/repotools-jts_importURLMappings.log file. If any errors are displayed, or if you realize that you made a mistake in your mapping file, see Troubleshooting server rename to pinpoint and fix the problem.

  4. Start the Jazz Team Server and any distributed applications that are installed.

    At this point the applications will synchronize with the Jazz Team Server to apply the URL mappings and update their data warehouse data. This should take about five minutes for a small data set and up to 30 minutes or more for a very large data set.

  5. Log into the Jazz Team Server at https://new host:port/jts/serverRenameStatus. This starts the actual renaming process. When the rename is complete, you will be able to verify the rename and take any corrective action that is necessary. During the verification process, the Jazz Team Server and all applications will be placed in read-only mode, but you will be able to browse data, and look for broken links and unmapped URLs. See Verifying URLs and links after a server rename for details.
  6. Before completing the verification process, ensure that you have performed any additional product-specific verifications described at Completing the server rename verification process. When you are confident that the renamed data is correct, click the I have verified the server rename ... check box and click Finish.

    At this point, the Jazz Team Server and all registered applications will exit read-only mode and normal product use can resume.

  7. Full production only: If you have a second Jazz Team Server or additional applications that are linked to the renamed Jazz Team Server, you must run repotools-jts -importURLMappings on the second Jazz Team Server.

    This step is necessary to update the links from the second server to the renamed server.

    Important: Do not generate a new mapping file. You must use the same mapping file that you used for the first renamed server.
    1. Copy the edited mappings file from the first server to the second server.

      Be sure to include any corrective mappings that you applied from the verification process.

    2. Review the mapping file and if necessary, remove any source-target pairs that you do not want to apply to the second server.
    3. Perform the rename on the second server by repeating Steps 3 through 6 on the second Jazz Team Server.

What to do next

After the steps in this task are done, complete the steps in Completing the server rename for Lifecycle Query Engine to re-add LQE and regenerate the index.

Feedback