Plan your upgrade

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

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, CVS or Perforce 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 Software requirements for CollabNet TeamForge 8.1 to understand what it takes to run TeamForge 8.1 with integrations.

Upgrade path

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

Services and hosts

TeamForge consists of five interrelated services (such as 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.

Site-wide reporting

TeamForge 6.1.x and later let site administrators track user logins.

If your users want site-wide reporting feature enabled, you'll have to turn on a service known as extract-transform-load (ETL), during the upgrade process. You'll also have to configure a new database called the datamart. These elements are turned off by default.

After your site is upgraded, you can also choose to move these new services off to one or more separate servers, the same as you can do with the existing TeamForge services.

Search re-indexing

If you are upgrading from TeamForge 6.1.1, 6.2 (including Patch 1) or 7.0 to TeamForge 8.1, you can run the indexupgrade.py script, which converts the Lucene 3.x indices to Lucene 4.4 format. No need to run this script if you are upgrading from TeamForge 7.1 or later to 8.1. For more information about the indexupgrade.py script, see Upgrade TeamForge search index to Lucene 4.x format. However, if you choose to re-index data, it takes a lot of time and the search service would have to be down till then. Instead, if you choose to upgrade your existing indices, you can convert your site's search indices to Lucene 4.x format quickly using the indexupgrade.py script with less downtime of the search service.
If you are upgrading from TeamForge 6.1 or earlier versions to TeamForge 8.1, you must re-index your site completely. This could be time consuming and depends on the size of data.

Branding changes

Every release of TeamForge can bring changes to the look and feel of the product. TeamForge 8.1 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.6 is installed automatically when you install TeamForge 8.1. 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 8.1 supports Oracle server 11G (R1 and R2) and Oracle client 11g.
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.6 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.6 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. GIT integration is not supported with Oracle database.

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.6 and 7.x

Though TeamForge 8.1 can run on RHEL/CentOS 6.6, it is a best practice to upgrade to TeamForge 8.1 on the most recent version of RHEL/CentOS supported by TeamForge, which in this case is RHEL/CentOS 7.1. However, choosing between RHEL/CentOS 6.6 and 7.1 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.x, CollabNet recommends that you have Black Duck Code Sight run on a separate RHEL/CentOS 6.6 server if you choose upgrade to TeamForge 8.1 on a RHEL/CentOS 7.x server.