Plan your upgrade

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

Attention: Before you begin, see TeamForge 16.7 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 Review Board, Nexus, Black Duck Code Sight, 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, Black Duck Code Sight, 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 16.7 with integrations.

Upgrade path

TeamForge 16.7 upgrade instructions are for upgrading from TeamForge 16.3 (including patch releases, if any) to TeamForge 16.7. Contact CollabNet Support if you want to upgrade from TeamForge 8.2 or earlier versions to TeamForge 16.7.

One-hop upgrade compatibility for TeamForge 16.7

Note:

The TeamForge 16.7 installer supports one-hop upgrade from TeamForge 7.2 or later versions only.

During an upgrade, the TeamForge 16.7 migration script detects the TeamForge version you run, checks if it's TeamForge 7.2 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 7.2 or later and then upgrade to TeamForge 16.7.

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 16.7 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.3.12 is installed automatically when you install TeamForge 16.7. 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 16.7 supports Oracle server 12c and Oracle client 12c.
Oracle express edition is not supported for both client and server.
Black Duck Code Sight (BDCS) 2.1.3 was tested with PostgreSQL 9.3.12 only. BDCS with Oracle was not tested. If you want BDCS, you may install BDCS on the PostgreSQL database that is installed by default during TeamForge installation.
Review Board 2.0.11 was tested with PostgreSQL 9.3.12 only. Review Board with Oracle was not tested. Note that Review Board must be installed on the TeamForge application server and therefore uses the PostgreSQL database that is installed by default during TeamForge installation.
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.2

Though TeamForge 16.7 can run on RHEL/CentOS 6.8, it is a best practice to upgrade to TeamForge 16.7 on the most recent version of RHEL/CentOS supported by TeamForge, which in this case is RHEL/CentOS 7.2. However, choosing between RHEL/CentOS 6.8 and 7.2 depends on whether or not you 'already have' Black Duck Code Sight.

As Black Duck Code Sight 2.1.3 has no support for RHEL/CentOS 7.2, CollabNet recommends that you have Black Duck Code Sight run on a separate RHEL/CentOS 6.8 server if you choose upgrade to TeamForge 16.7 on a RHEL/CentOS 7.2 server.

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

Attention: TeamForge installer is being 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 16.7 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.