Plan your upgrade

As the first step in upgrading to TeamForge 17.4, consider some key things that will affect how your new site works.

Attention: Before you begin, see TeamForge 17.4 Release Notes and understand what's new with TeamForge install and upgrade. It is recommended to set up a TeamForge Stage Server before you upgrade your Production Server. See Set up a TeamForge Stage Server.

Overview

A TeamForge site consists of a core TeamForge application and several tightly integrated services that support it. In addition, you can integrate TeamForge with other third party applications such as Review Board, Nexus, Git, and so on.

The core TeamForge application provides the Web interface that users see, and the API that other applications can interact with. It also includes the file system where some user content is stored, such as wiki pages.
The site database is where most of the user-created content is stored and accessed. Documents, discussion posts, tracker artifacts, project administration settings: all that sort of thing lives in the database.
The source control server ties any number of Subversion or CVS repositories into the TeamForge site.
The Extract Transform and Load (ETL) server pulls data from the site database and populates the datamart to generate charts and graphs about how people are using the site.
The datamart (Reports DB) is an abstraction of the site database, optimized to support the reporting functionality.

Integrations

TeamForge supports integration with a wide array of third party applications such as Review Board, Git, Nexus, Jira and so on. As a customer you may or may not always want (or have) all of TeamForge's supported integrated applications. It's also quite possible that some of the integrated applications may not always run on all the platforms supported by TeamForge.

To accommodate a wider audience, by default, TeamForge install and upgrade instructions include steps to integrate such third party applications with TeamForge. However, use your discretion to ignore and skip such steps if they are not relevant to your site. See TeamForge installation requirements to understand what it takes to run TeamForge 17.4 with integrations.

Upgrade path

TeamForge 17.4 upgrade instructions are for upgrading from TeamForge 17.1 (including update releases, if any) to TeamForge 17.4. Contact CollabNet Support if you want to upgrade from TeamForge 16.10 or earlier versions to TeamForge 17.4.

One-hop upgrade compatibility for TeamForge 17.4

Note:

The TeamForge 17.4 installer supports one-hop upgrade from TeamForge 16.3 or later versions only.

During an upgrade, the TeamForge 17.4 migration script detects the TeamForge version you run, checks if it's TeamForge 16.3 or later, and if 'true', proceeds with the data migration.

The migration script aborts with an error message if it detects TeamForge 7.2 or earlier versions. You must upgrade your site to TeamForge 16.3 or later and then upgrade to TeamForge 17.4.

Services and hosts

TeamForge consists of several interrelated services (such as the TeamForge application, database, datamart, indexer and so on) and other integrated applications that can run on separate hardware or share one or more servers in various configurations. If you aren't the person who first installed your current TeamForge site (or maybe, even if you are), it's essential to catalog the hosts where your services are running and to know what configuration has been applied to them.

Branding changes

Every release of TeamForge can bring changes to the look and feel of the product. TeamForge 17.4 is no exception. If you have edited files in your site's branding repository (that's how you customize the look and feel of the product), you must download the new branding package and check into your branding repository the new versions of any files you have edited. See Customize anything on your site for instructions.

PostgreSQL or Oracle?

PostgreSQL 9.6.1 is installed automatically when you install TeamForge 17.4. If you intend to use Oracle, CollabNet recommends that you let the installer run its course, make sure things work normally, and then set up your Oracle database and switch over to it.

If you want to use Oracle as your database, consider the following points:

TeamForge 17.4 supports Oracle server 12c and Oracle client 12c.
Oracle express edition is not supported for both client and server.
Review Board 2.5.6.1 was tested with PostgreSQL 9.6.1 only. Review Board with Oracle was not tested. Note that Review Board (application) must be installed on the TeamForge application server and therefore uses the PostgreSQL database that is installed by default during TeamForge installation. However, Review Board database can be installed on a separate server.
GIT integration works only with PostgreSQL. The Git integration will use PostgreSQL even if your TeamForge site uses Oracle.

The efficiency of your database can have an impact on your users' perception of the site's usability. If your site uses a PostgreSQL database (which is the default), you may want to consider tuning it to fit your specific circumstances. The default settings are intended for a small-to-medium site running on a single server. See What are the right PostgreSQL settings for my site? for recommendations from CollabNet's performance team on optimizing PostgreSQL for different conditions.

Upgrade considerations for RHEL/CentOS 6.8 and 7.3

Though TeamForge 17.4 can run on RHEL/CentOS 6.8, it is a best practice to upgrade to TeamForge 17.4 on the most recent version of RHEL/CentOS supported by TeamForge, which in this case is RHEL/CentOS 7.3.

TeamForge 16.7 and later versions support automatic JAVA_HOME configuration. Hence, remove the JAVA_HOME token while configuring your site-options.conf file.

Attention: TeamForge installer has been optimized quite a bit. It's likely that you might come across a lot of warning messages while upgrading from TeamForge 8.2 (or earlier) to TeamForge 17.4 on the same hardware (when you run the yum install teamforge command). You can safely ignore such warning messages and proceed with the upgrade.

'Team' feature and its implications

Important:

Ignore this if you are upgrading from TeamForge 8.0 to 8.1 or later.

With the 'Team' feature added to TeamForge 8.0, any field by the name 'team', if already existing in your trackers, might cause a conflict while running the migrate.py script. To overcome such a conflict, follow the steps in the following Troubleshooting FAQ.

What's new in TeamForge 17.4

End-of-life for APIs / Event handlers

TeamForge SOAP50 APIs and event handlers are no longer supported in TeamForge 16.10 and later. Instead, Customers can use the latest TeamForge SOAP/REST APIs.