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

To perform a server rename, you must obtain a feature key file from IBM Software Support. When you contact IBM Support, mention that you are requesting a server rename feature key file. The key file is named ImportURLMappings.activate. Copy the file to the JazzInstallDir/server/conf directory for the applications that you will rename. The key is only needed to execute the repotools importURLMappings command.
Before you proceed with the rename, check that the required version of the ELM software is installed and that your environment meets the criteria for a server rename. See Software version requirements and Supported scenarios for using server rename for details.
Decide whether you are going to move the deployment to new hardware or keep the same hardware (rename-in-place). In the following steps, your current server environment is called the source environment. The server environment that you are moving to is called the target environment. If you are performing a rename-in-place, the target environment refers to a new location on the same server, or set of servers in a distributed deployment.
Review the topics in the Impact of server rename on the IBM Engineering Lifecycle Management section to understand the actions you need to take when the Jazz® Team Server and ELM applications are renamed.
Review the Impact of server rename on Lifecycle Query Engine and the Link Index Provider topic.
Before you proceed with the rename, review the post-rename steps for Report Builder.
Decide whether you are going to keep the existing application server or migrate to a new one. If you are planning to move to a new application server, see one of the following topics as appropriate to your environment: Switching from Apache Tomcat to WebSphere Application Server or Changing WebSphere Application Server installations and instances.
Decide whether you are going to keep the existing database or move to a new one. If you are planning to move to a new database, see one of the following topics as appropriate to your environment: Moving the IBM Engineering Lifecycle Management (ELM) databases to a different database server or Changing the IBM Engineering Lifecycle Management (ELM) databases to a different database vendor.
Setting up server rename can take several attempts. If your setup takes more than one attempt, you will need to restore your environment to a clean state between attempts. For instructions on restoring to a clean state, see Recovering from common problems.

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

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.
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.

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.

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.
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 ELM database for additional steps.

Note: The Report Builder database is in the server/conf/rs/db folder.

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

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

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.

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:
  - 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
   # 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.
  - 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 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.
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.
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.
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.
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.
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.
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.
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.