Staging a test environment for the upgrade process

Edit online

You can set up a test environment to verify the upgrade process with real data before you upgrade your production server. You must be careful to maintain the public URL in the test environment to avoid issues with absolute URL links between the test environment and Jazz® Team Server and other applications that are in production.

Before you begin

Ensure that you have a backup copy of the production databases for all the applications for which you want to test the upgrade process.
You can also stage your test environment by using virtual machines. If you use virtual machines, use the same number of virtual machines as in the production installation to replicate the deployment pattern.

About this task

The IBM® Engineering Lifecycle Management applications are uniquely identified on a network by their public URL, which is also known as a front-side URL or public URI root. The server and applications generate absolute URLs for resources that are used in stored artifacts, mail notifications, feeds, web access, and for stable resource identification across all applications. These URLs ensure uniform access to all resources that are stored in various repositories and provide consistent query results for artifacts.

These URLs also create requirements when you test the upgrade process by using real production data in a staged environment. The persisted URLs in the repositories refer to artifacts by their production public URL. These references occur for cross-application links, such as a link between a test artifact and a work item, and can also occur for artifacts that are stored in a single application repository with self-referencing URLs. Ensure that the repositories for the test environment and the actual production are isolated from each other.

The ideal setting for a staged environment is a completely isolated subnet with no visibility to the real production server. Where such a setup is not possible, you can use simpler techniques with caution.

Consider the following techniques which provide both isolation and a useful testing environment. The techniques are listed in increasing order of complexity. For each technique, your must first restore a copy of the production database to a test database server. Maintain the same configured public URL for each application and the Jazz Team Server.

Option 1: Test all server applications on one server

You can test everything on one server if the applications to test are hosted on the same server in the production environment and if the test server has enough resources.

Edit the hosts file on the test server. You can configure an alias for the server by adding the following entry to your system hosts file: 127.0.0.1 qualified.hostname. Substitute qualified.hostname with the fully qualified host name that is used in your production public URL. The hosts file is in the following location:
- Linux: /etc/hosts
- Mac: /etc/hosts
- Microsoft Windows: C:\windows\system32\drivers\etc\hosts
- IBM i: Run the CFGTCP command and then enter option 10.

Note: Modifying the hosts file is only for testing purposes in a staging environment.

Option 2: Test with multiple servers

You can use this option if you have multiple applications on different servers.

Record how the public URLs for each server map to the IP addresses of the test servers that are used.
Edit the hosts file on each test machine by using mappings for all of the test machines that act as staging servers.

Option 3: Separate the subnet

This option provides the greatest isolation, but is the most complex.

Place the test servers and test clients behind a router with no access to the production network.
Configure a DNS server within this subnet and map the public URL host names to the IP addresses of the test servers that you are using.

Testing clients

To validate your staging environment, you must connect clients to the staged server, for example, a web browser or the Engineering Workflow Management rich client. The connections must resolve to the hosts in the staging environment and not the production environment. You should either run these clients on one of the servers in the staging environment, or use a dedicated client workstation that includes all the host mappings and is not used in any production environment.

Procedure

Note: The following procedure is an example for staging a server that hosts Jazz Team Server and the Change and Configuration Management application. Repeat the same procedure for each additional staging environment or application.

Restore the backup of the production database to the staging database server.
Make a copy of the production installation directory of the application and the Jazz Team Server that is being upgraded and paste it into the same location on the staging server.

Note: Do not copy the text indices. Starting in version 6.0.6.1, the Apache Lucene full-text search engine was upgraded to a more recent version. As a result, all existing full-text search indexes that were created in 6.0.6 or earlier must be rebuilt. For details, see this workaround article.
Important: Replace the database connection parameters in the teamserver.properties file in the server/conf/jts and server/conf/ccm directories to point to the connection parameters for the staging copy of the databases.
- Update the connection string value of com.ibm.team.repository.db.jdbc.location for the application databases.
- Update the connection string value of com.ibm.team.datawarehouse.db.jdbc.location to modify the connection to the data warehouse database.
This step is crucial so that when you run the upgrade, you connect to the test copy of the production databases.
Edit the hosts file on the staging server so that all URLs point to the staging server and not the production server. Note that you can use any of the methods described in this topic.
Example:
Staging server
```
<IP address staging server> host.example.org
```
If any of the production servers being upgraded have friend relationships configured to other production servers that are not being staged, add a host entry for those systems and route them to a nonexistent IP address. Example:
```
<dummy IP address for non_staged_production_server>  <non_staged_production_server_hostname.example.org>
```
Repeat this process for each non-staged friend relationship. Example:
```
<dummy IP address for non_staged friend server>  <non_staged friend production server>
```
Start the staging server. To check the configuration, create a comment in your production installation and verify that you do not see it in the staging environment.
Stop the staging server.
Install the new version of Jazz Team Server and applications on your staging server.
Follow the upgrade procedure in the Interactive Upgrade Guide to upgrade your installation to the new version.