Moving a pilot or full production deployment by using server rename

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

Before you begin

Note: After the rename, the source ELM servers 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 to rename. A repotools command is provided to generate an initial mapping file for you. The mapping file contains source-target pairs for the JTS and all applications, and any other URLs contributed by applications. See Mapping file for server rename for details about the mapping file. See Topologies and mapping files for the pilot to production scenario for sample topology diagrams and mapping files.

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 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, and any other URLs contributed by applications.

  2. If your deployment includes the Global Configuration Management application or the Link Index Provider application and you move either application to a different Jazz Team Server, or you rename the server, you must update the application property on the server Administration page.
    1. Log in to the Administration page of the Jazz Team Server. Point your web browser to the following URL: https://fully qualified hostname:9443/jts/admin
      Remember: The fully qualified hostname is the host name along with the DNS domain reference of the machine on which the Jazz Team Server is installed.
    2. On the Administration page, click the Server tab, and then in the left pane, under Configuration, click Advanced Properties.
    3. On the Advanced Properties page, complete the following steps.
      1. If your deployment includes the Global Configuration Management application, go to the Global Configuration SDK section and update the Global Configuration Provider URL property with the URL of the renamed server, for example https://fully qualified hostname:9443/gc/.
      2. If your deployment includes the Link Index Provider application, go to the Links Component section and update the Link index provider URL property with the URL of the renamed server, for example https://fully qualified hostname:9443/ldx/.
    4. At the top of the page, click Save.
  3. Back up the existing source environment and copy text indexes 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 ELM applications that are registered with the Jazz Team Server.

      In addition, stop any other applications that are affected by the server rename, such as the Jazz Build Engine, or any affected integrations, such as Rational® ClearCase® or Rational ClearQuest®.

      Note: While the servers are down, users are unable to create or traverse links from any external systems that are integrated with the ELM deployment about to be renamed.
    2. Back up the databases for the source environment, including the Jazz Team Server database; the databases for the Change and Configuration Management, Quality Management, Global Configuration Management, IBM Engineering Lifecycle Optimization - Engineering Insights, Data Collection Component, Lifecycle Query Engine, Link Index Provider, and Report Builder applications; and the data warehouse database. If you are changing the database server or vendor, see Moving the CLM database for additional steps.
      Note: The Report Builder database is in the server/conf/rs/db folder.
    3. Copy the JFS/text indexes 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 mounted on the network. If you cannot mount the drives on the network 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/ccm/indices TargetJazzInstallDir/server/conf/ccm
      cp -R SourceJazzInstallDir/server/conf/dcc/indices TargetJazzInstallDir/server/conf/dcc
      cp -R SourceJazzInstallDir/server/conf/gc/indices TargetJazzInstallDir/server/conf/gc
      cp -R SourceJazzInstallDir/server/conf/qm/indices TargetJazzInstallDir/server/conf/qm
      cp -R SourceJazzInstallDir/server/conf/relm/indices TargetJazzInstallDir/server/conf/relm
      cp -R SourceJazzInstallDir/server/conf/rm/indices TargetJazzInstallDir/server/conf/rm
      cp -R SourceJazzInstallDir/server/conf/lqe/indexTdb TargetJazzInstallDir/server/conf/lqe
      cp -R SourceJazzInstallDir/server/conf/lqe/testIndex TargetJazzInstallDir/server/conf/lqe
      cp -R SourceJazzInstallDir/server/conf/lqe/shapeTdb TargetJazzInstallDir/server/conf/lqe
      cp -R SourceJazzInstallDir/server/conf/lqe/shapeText TargetJazzInstallDir/server/conf/lqe
      cp -R SourceJazzInstallDir/server/conf/ldx/indexTdb TargetJazzInstallDir/server/conf/ldx
      cp -R SourceJazzInstallDir/server/conf/ldx/testIndex TargetJazzInstallDir/server/conf/ldx
    4. Copy the application configuration files from the source installation to the target production installation. As with the previous step, the next examples are for a Linux server and assume that the drives for the target production computers are mounted on the network.
      cp SourceJazzInstallDir/server/conf/jts/teamserver*.properties TargetJazzInstallDir/server/conf/jts
      cp SourceJazzInstallDir/server/conf/ccm/teamserver*.properties TargetJazzInstallDir/server/conf/ccm
      cp SourceJazzInstallDir/server/conf/dcc/teamserver*.properties TargetJazzInstallDir/server/conf/dcc
      cp SourceJazzInstallDir/server/conf/gc/teamserver.properties TargetJazzInstallDir/server/conf/gc
      cp SourceJazzInstallDir/server/conf/qm/teamserver*.properties TargetJazzInstallDir/server/conf/qm
      cp SourceJazzInstallDir/server/conf/relm/teamserver.properties TargetJazzInstallDir/server/conf/relm
      cp SourceJazzInstallDir/server/conf/rm/teamserver.properties TargetJazzInstallDir/server/conf/rm
      cp SourceJazzInstallDir/server/conf/rs/app.properties TargetJazzInstallDir/server/conf/rs
      cp SourceJazzInstallDir/server/conf/lqe/lqe.properties TargetJazzInstallDir/server/conf/lqe
      cp SourceJazzInstallDir/server/conf/lqe/dbconnection.properties TargetJazzInstallDir/server/conf/lqe
      cp SourceJazzInstallDir/server/conf/lqe/lqe.node.id TargetJazzInstallDir/server/conf/lqe
      cp SourceJazzInstallDir/server/conf/lqe/lqe.key TargetJazzInstallDir/server/conf/lqe
      cp SourceJazzInstallDir/server/conf/ldx/lqe.properties TargetJazzInstallDir/server/conf/ldx
      cp SourceJazzInstallDir/server/conf/ldx/dbconnection.properties TargetJazzInstallDir/server/conf/ldx
      cp SourceJazzInstallDir/server/conf/ldx/lqe.node.id TargetJazzInstallDir/server/conf/ldx
      cp SourceJazzInstallDir/server/conf/ldx/lqe.key TargetJazzInstallDir/server/conf/ldx
    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.
  4. Perform the offline portion of server rename by importing the mapping file into the target production Jazz Team Server, by using the repotools-jts -importURLMappings command.
    1. If you have an all-in-one deployment, import the mappings file by using the repotools-jts -importURLMappings command as follows:
      • For Windows operating systemrepotools-jts.bat -importURLMappings fromFile=".\mappings.txt"
      • For Unix operating systemsFor Linux operating system./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
         # Remote DCC server
         w:/JazzTeamServer/server/conf
         # Remote GC server
         v:/JazzTeamServer/server/conf
         # Remote RELM server
         u:/JazzTeamServer/server/conf
         # Remote RS server
         t:/JazzTeamServer/server/conf

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

      • For Windows operating systemrepotools-jts.bat -importURLMappings fromFile=".\mappings.txt" serverConfFile=".\serverConf.txt"
      • For Unix operating systemsFor Linux operating system./repotools-jts.sh -importURLMappings fromFile="./mappings.txt" serverConfFile="./serverConf.txt"
    3. If you have a distributed ELM 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, dcc, gc, qm, relm, rm, and rs. 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 must contact the Jazz Team Server at its new location. The .mappingEvent file contents are the same for a Jazz Team Server and its registered applications.

    Note: Rename servers that are running on z/OS® by using sample JCL member HLQ.SBLZSAMP(BLZRENAM). See the comment header of BLZRENAM for detailed customization instructions.

    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.

  5. If you are using IBM HTTP Server (IHS), reconfigure the plugin-cfg.xml file to point to the target environment. Otherwise, unless the target system is isolated from the network, there is a risk of being redirected to the production servers that are configured in this file.
  6. Follow these steps to start Jazz Team Server and ELM applications:
    1. Start Jazz Team Server first and verify you can access it through its new URL.
    2. Start all the other applications and ensure each application completes its initialization and connects to Jazz Team Server.
    3. Because Jazz Team Server was started first, it initially fails to connect to all applications and stops polling.
    4. Restart Jazz Team Server to start to poll each application.
  7. Log in to the Jazz Team Server.
    • If you are renaming the Jazz Team Server, log in to the target server at https://new host:port/jts/serverRenameStatus.
    • If you are renaming one or more of the ELM applications but not the Jazz Team Server, log in to the source server at https://source host:port/jts/serverRenameStatus.

    Logging in to the Jazz Team Server starts the actual renaming process. The ELM applications will synchronize with the Jazz Team Server to apply the URL mappings and update their data warehouse data. The synchronization should take about 5 minutes for a small data set and up to 30 minutes or more for a large data set. When the rename is complete, you can verify the rename and take any corrective action that is necessary. During the verification process, the Jazz Team Server and all ELM applications are placed in read-only mode, but you are able to browse data, and look for broken links and unmapped URLs. See Verifying URLs and links after a server rename for details.

  8. Perform additional product-specific verifications described at Completing the server rename verification process.
    Tip: Some verifications can only be completed after deactivating read-only mode, perform those steps after you later check the I have verified the server rename box and complete the verification wizard.
  9. When you are confident that the renamed data is correct, click the I have verified the server rename check box and click Finish.

    The Jazz Team Server and all registered applications will exit read-only mode and normal product use can resume.

  10. Perform any additional post-server rename steps that are required for integration with other components and products such as the Jazz Build Engines, Jazz Reporting, Engineering Workflow Management clients, Rational ClearQuest, or Rational ClearCase. For details, see Impact of server rename on the IBM Engineering Lifecycle Management.
  11. Full production only: If you have a second Jazz Team Server or additional ELM 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 4 through 9 on the second Jazz Team Server.

video icon Video

Jazz.net channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community

Jazz.net
Jazz.net forums
Jazz.net library

support icon Support

IBM Support Community
Deployment wiki