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 ELMInstallDir/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 Engineering Lifecycle Management 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 Engineering Lifecycle Management 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 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 databases to a different database server or Changing the IBM Engineering Lifecycle Management 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 Engineering Lifecycle Management 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 Jazz Team Server 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, 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 beginning 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 Engineering Lifecycle Management 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 DevOps Code ClearCase® or ClearQuest® .

Note: While the servers are down, users are unable to create or traverse links from any external systems that are integrated with the Engineering Lifecycle Management deployment about to be renamed.
Back up the databases for the source environment, including the Jazz Team Server database; the databases for the Engineering Workflow Management , Engineering Test 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 Configuring your deployment after a database server move 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 prLink Index Providerduction 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 SourceELMInstallDir/server/conf/jts/indices TargetELMInstallDir/server/conf/jts
cp -R SourceELMInstallDir/server/conf/ccm/indices TargetELMInstallDir/server/conf/ccm
cp -R SourceELMInstallDir/server/conf/dcc/indices TargetELMInstallDir/server/conf/dcc
cp -R SourceELMInstallDir/server/conf/gc/indices TargetELMInstallDir/server/conf/gc
cp -R SourceELMInstallDir/server/conf/qm/indices TargetELMInstallDir/server/conf/qm
cp -R SourceELMInstallDir/server/conf/relm/indices TargetELMInstallDir/server/conf/relm
cp -R SourceELMInstallDir/server/conf/rm/indices TargetELMInstallDir/server/conf/rm
cp -R SourceELMInstallDir/server/conf/lqe/indexTdb TargetELMInstallDir/server/conf/lqe
cp -R SourceELMInstallDir/server/conf/lqe/testIndex TargetELMInstallDir/server/conf/lqe
cp -R SourceELMInstallDir/server/conf/lqe/shapeTdb TargetELMInstallDir/server/conf/lqe
cp -R SourceELMInstallDir/server/conf/lqe/shapeText TargetELMInstallDir/server/conf/lqe
cp -R SourceELMInstallDir/server/conf/ldx/indexTdb TargetELMInstallDir/server/conf/ldx
cp -R SourceELMInstallDir/server/conf/ldx/testIndex TargetELMInstallDir/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 SourceELMInstallDir/server/conf/jts/teamserver*.properties TargetELMInstallDir/server/conf/jts
cp SourceELMInstallDir/server/conf/ccm/teamserver*.properties TargetELMInstallDir/server/conf/ccm
cp SourceELMInstallDir/server/conf/dcc/teamserver*.properties TargetELMInstallDir/server/conf/dcc
cp SourceELMInstallDir/server/conf/gc/teamserver.properties TargetELMInstallDir/server/conf/gc
cp SourceELMInstallDir/server/conf/qm/teamserver*.properties TargetELMInstallDir/server/conf/qm
cp SourceELMInstallDir/server/conf/relm/teamserver.properties TargetELMInstallDir/server/conf/relm
cp SourceELMInstallDir/server/conf/rm/teamserver.properties TargetELMInstallDir/server/conf/rm
cp SourceELMInstallDir/server/conf/rs/app.properties TargetELMInstallDir/server/conf/rs
cp SourceELMInstallDir/server/conf/lqe/lqe.properties TargetELMInstallDir/server/conf/lqe
cp SourceELMInstallDir/server/conf/lqe/dbconnection.properties TargetELMInstallDir/server/conf/lqe
cp SourceELMInstallDir/server/conf/lqe/lqe.node.id TargetELMInstallDir/server/conf/lqe
cp SourceELMInstallDir/server/conf/lqe/lqe.key TargetELMInstallDir/server/conf/lqe
cp SourceELMInstallDir/server/conf/ldx/lqe.properties TargetELMInstallDir/server/conf/ldx
cp SourceELMInstallDir/server/conf/ldx/dbconnection.properties TargetELMInstallDir/server/conf/ldx
cp SourceELMInstallDir/server/conf/ldx/lqe.node.id TargetELMInstallDir/server/conf/ldx
cp SourceELMInstallDir/server/conf/ldx/lqe.key TargetELMInstallDir/server/conf/ldx

Copy the mapping file to the TargetELMInstallDir\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.
- 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.
- 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 Engineering Workflow Management server
   x:/ELMInstallDir/server/conf
   # Remote Engineering Test Management server
   y:/ELMInstallDir/server/conf
   # Remote Engineering Requirements Management DOORS Next server
   z:/ELMInstallDir/server/conf
   # Remote DCC server
   w:/ELMInstallDir/server/conf
   # Remote GC server
   v:/ELMInstallDir/server/conf
   # Remote RELM server
   u:/ELMInstallDir/server/conf
   # Remote RS server
   t:/ELMInstallDir/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"
- If you have a distributed Engineering Lifecycle Management 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 ELMInstallDir/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 Engineering Lifecycle Management 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 Engineering Lifecycle Management 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 Engineering Lifecycle Management 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 Engineering Lifecycle Management 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, ClearQuest , or DevOps Code 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 Engineering Lifecycle Management 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.

What to do next

Proceed with changing the context root. For more information, see Changing the context root.