Moving Jazz Servers and URI Stability with CLM 2011
Introduction
This article is meant to clear up some common questions and misconceptions about the possibilities and issues surrounding the movement of Jazz servers, issues surrounding URL stability, and how all of this can impact your Rational jazz CLM 2011 architecture. The basic issues imposed by a RESTful architecture will have a definite impact on the solution architecture that you put into place to host your CLM 2011 solution. What you do will depend on your overall software development tools strategy, as well as your user community.
We try to keep in mind in this article that while some things may be possible from a technical standpoint, they are not good paths to go down due to operational, organization scaling or performance concerns. So while it may be technically possible to deploy the CLM 2011 solution with a Derby database, the limitations of this approach make it an intelligent thing to avoid for performance and scalability reasons. The key here is to not just ask the technical questions (“Can I deploy with Derby as my back-end database?”), but to instead ask intelligent questions ((“Can I support 1000 concurrent CLM users with a deployment on a Derby database?”). The answer to the first question is “Yes”, but following this advice will get you into trouble. Be sure to think in terms of the solution for your end users, and not get too focused on the technical.
The rest of this article is posed as a series of frequently asked questions, along with some answers and some explanation of the answer. We will try to focus on the intelligent questions, and provide you with intelligent answers. You may note that we have a number of links to the Infocenter, which is a very good source of information.
Basic Concepts
Often an understanding of some of the basic concepts involved with a Jazz solution make things much more clear.Why is the URL so important?
The Jazz architecture is based on some basic concepts, like REST and Internet addressable and discoverable resources. For a funny, but simple and easy to understand explanation of REST, read Ryan Tomayko’s post on How I Explained REST to my Wife. The Jazz RESTful architecture has the various artifacts manipulated by the Jazz based tools. You can gain some basic understanding by looking the Infocenter entry on Planning yur URI’s.
In the Jazz environment, artifacts are considered resources, and these resources are all accessible by using a URI (or web) reference. That is how they are accessed. Relationships between artifacts are expressed as hyper-links between two of these REST based artifacts. So think about this. Changing the name of the base URI for your server would invalidate every resource in your repository. It would also break any of the links to your resources from other applications.
Was the public URI required in the Jazz 2.x products?
It was, but it was not enforced. There may be instances where a server was configured without a public URI. We strongly recommend that you set it, and choose a common stable URL that users have been using to access the server. You must configure a public URI prior to upgrade.
Is a public URI required in the Jazz 3.x products?
Yes. We have added better guidance in the Infocenter and in the server setup user interface. Setup also performs more validation to discourage configuring a potentially unstable URL (e.g., IP address, short name, localhost, etc). Unless you are setting up a demonstration environment which you will not need the data from, do NOT override these warnings, and make sure that you select a fully qualified domain name as the basis for your public URI.
Server Moves and Renames
Our Jazz customers often have questions about renaming and moving the application servers supporting the Jazz tools.Can I move my Jazz/RTC installation to another server?
The Jazz applications can be moved to different physical machines as long as they keep the same public server root URI. A stable server URI can be preserved by DNS or reverse proxy topology. Setting up a reverse proxy server will allow you to retain the previous public server root URI, while hosting the application on a server with a different name. Remember to always use a fully qualified domain name for your public server root URI.
How can I change the public URI of my Jazz application server? Or my Jazz Team Server?
It is not currently supported to change the public URI in a CLM 3.0 solution, as links will be broken between the applications. We have heard requests from some clients using a single product (a.k.a. “product in a silo”, e.g., RTC 3.0 only) for any utilities or workarounds even if it would result in some data loss or broken links. The development team is exploring possible workarounds for silo installations.
Can I use repotools export and import to do a server move?
This is not supported.
Repotools export and import are for database migration: e.g., migrating from one database vendor to another, or from one version/platform of a database to another, where native backup and restore is not supported by the vendor. Generally the off-line backup and restore facilities provided by an enterprise database will be much faster than repotools export and import.
There is currently not any processing in repotools export or import that will fix all of the URL references.
I changed the public URI and it seemed to work. What’s broken?
There are numerous internal references within a Jazz repository. Some examples of this are:
- Links in opaque resources (dashboards, RTC enterprise extensions)
- Project area URLs
- User URLs
- Facts in the data-warehouse – The data-warehouse tables store hashed URLs as identifiers for resources
- Fully qualified URLs in plans or work items
Can I change the public URI of an RTC 2.x server?
Officially this is not supported or recommended. However, the extent to which URLs are stored in RTC 2.x is not as pervasive as in RTC 3.x or in any of the linked CLM repositories, especially if there are no cross-repository or C/ALM links. You can change the public URL prior to upgrade, with some data loss:
- Fully qualified URLs in work items will be broken
- Work item links in emails will be broken
- Artifact links across repositories (e.g. to other RTC servers or RQM or RRC) will be broken
- Facts in the data-warehouse – In RTC 2.x, this would only affect customers also using Insight for reporting
- Any integrations to other tools will be broken
This was targeted to a specific use case where a CQ server was moved, to allow fixing work item artifact links in the RTC repository. This is NOT a general purpose server move solution, although it will likely be a part of any server move solution that is made available in the future.
Databases
Application servers are not the only servers supporting a Jazz solution. We also get questions about the database servers.Can I move my database from one database server to another?
Yes you can. The database location is configured in the teamserver.properties configuration file, and it is not persisted anywhere else. Remember that you want to minimize latency between the application server and the database server, and it is not recommended to distribute it over a WAN. The latency between the Jazz application servers and their associated database repositories will have a direct impact on the performance of your CLM solution, which is what you would expect.
Is there some set of SQL I can run in the database to fix everything?
The structure of the databases that support the Jazz applications is an internal implementation detail. The table structure is optimized for reads, and thus item contents are stored in blobs. Additionally, the format of some resource content is opaque to the framework and component specific (e.g., binary, rdf, xml, etc). There is no trivial solution mechanism to reliably process all the data in the database.
Testing and Staging
Sometimes you just need a copy of the data that you already have, in order to provide a testing or staging environment, or to provide a demo environment. Here are some common questions on those topics.I need to replicate a repository to a testing and staging environment. How can I do that if I can’t change the public URI?
You can set up an isolated network where the hostnames are resolved to the test machine(s). Make sure that your testing clients also resolve to the test machines. See http://publib.boulder.ibm.com/infocenter/clmhelp/v3r0m1/topic/com.ibm.jazz.install.doc/topics/c_upgrade_staging_env.html for more information.
I have a test database that I use to give demos. I thought I could use export and import to put this on different machines or share it with others. What can I do?
Choose a test host name for your URL, e.g, rtcdemo.example.org. Anyone executing the demo can add this entry to their local hosts file and resolve it to the loopback address. This will allow you to run a demo on a single machine, with all of the artifact links kept intact.
For more information
- Infocenter – an online help resource for the Jazz tools
- Staging a test environment for the upgrade process – you can use this same technique to set up a staging environment for ANY reason
About the author
Daniel Toczala is the manager of the Jazz Jumpstart team, which helps enable IBM/Rational customers with Jazz based technologies. Daniel travels the world, but his home base is in New Hartford, NY, USA. He can be contacted at dtoczalaj@us.ibm.com.
Copyright © 2011 IBM Corporation
Yes