Plan your upgrade

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

Attention: Before you begin, see TeamForge 17.1 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.

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.1 with integrations.

Upgrade path

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

One-hop upgrade compatibility for TeamForge 17.1

Note:

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

During an upgrade, the TeamForge 17.1 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 17.1.

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.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.12 is installed automatically when you install TeamForge 17.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 17.1 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.3.12 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.1 can run on RHEL/CentOS 6.8, it is a best practice to upgrade to TeamForge 17.1 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 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 17.1 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.1

TeamForge Code Search (Elasticsearch)

Consider the following points while upgrading from TeamForge 16.10 (or earlier) to TeamForge 17.1 (or later) versions.
  • Code Search is now an integral part of TeamForge, which is installed by default during TeamForge installation.
  • You can install TeamForge Code Search either on the TeamForge Application Server or on a separate SCM integration Server. It is recommended to install TeamForge Code Search on a separate server if your site's indexing needs are considerably high (large number of repositories, for example).
  • TeamForge Code Search works with GIT and SVN repositories. TeamForge Code Search has no support for CVS repositories.
  • Installation of Elasticsearch is determined by adding the "codesearch" identifier to the SERVICES token of either the TeamForge Application Server or the SCM Integration Server (if Code Search runs on a separate server). Refer to the site-options.conf configuration section of TeamForge installation/upgrade instructions for more information.
  • Elasticsearch needs 2GB of JVM heap size by default on a TeamForge site. You must have adequate RAM to accomodate the JVM heap requirements of Elasticsearch in addition to the JVM heap requirements of other components such as Jboss, integrated applications, and so on.
  • If required, you can increase the JVM heap size for Elasticsearch. Set the ELASTICSEARCH_JAVA_OPTS token with the Elasticsearch JVM heap size required for your site.
  • Elasticsearch stores every document, which for code search is each source file that is indexed, and it has its index itself as well. As a rule of thumb, the index for a repository would be roughly the same size as the working copy for that repository but in practice it will likely be smaller. Consider that all binary files and all files greater than 1 MB are not indexed at all. So, obviously any repository that has a large working copy due to these types of files will have a much smaller index. By default, Elasticsearch compresses the original files using LZ4 compression. It also offers a "best_compression" codec that compresses the originals using DEFLATE algorithm. In TeamForge, indexes have been updated to use the maximum compression.
  • The Elasticsearch data and logs are stored in /opt/collabnet/teamforge folder. Log rotation, startup and so on are all managed the same way as other TeamForge services.
  • As Black Duck Code Sight (BDCS) is not supported:
    • remove all BDCS tokens from your site-options.conf file while upgrading to TeamForge 17.1 (or later). TeamForge create runtime fails otherwise. See Site options change log for a list of obsolete site-options.conf tokens.
    • there is no migration support for existing BDCS indexes. All the repositories should be indexed afresh post upgrade to TeamForge 17.1 (or later). The list of repositories to index, remains the same though. After upgrading to 17.1 (or later), whatever repositories were being indexed by BDCS are indexed by the new Code Search without any user intervention. However, if you had customized indexing for one or more repositories using the BDCS administration UI, such information will not have been migrated and would need to be done again, but that can now be done via the TeamForge UI.

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.

Parent topic: Upgrade TeamForge