Plan your installation or upgrade setup, hardware and software requirements and so on before you begin.

TeamForge Services

Before you plan your installation or upgrade, let us understand TeamForge and its services.

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 Nexus, Jenkins, Jira and so on. Some of the TeamForge services are mandatory and some are optional. You can install the services, all in one single server, or distribute them across two or more servers.

  • 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 Git/Gerrit 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.
  • Baseline is a TeamForge capability that lets you create snapshot of selected configuration items from a given TeamForge project at a given point in time. For more information, see TeamForge Baseline.
  • TeamForge Webhooks-based Event Broker, which is also referred to as the integration broker, is a webhooks-based message broker that pushes the messages of specific events received from a Publisher to a Subscriber. For more information, see TeamForge Webhooks-based Event Broker.

Here’s a list of available TeamForge services.

Service Mandatory/Optional Old Name Description
ctfcore Mandatory app Main TeamForge application server
search Mandatory indexer Indexing and searching
mail Mandatory NA (added in TeamForge 17.1) Email server
ctfcore-database Mandatory database Operational database
ctfcore-database-mirror Optional NA Mirror of operational database
codesearch Mandatory codesearch Code Search
etl Optional etl ETL for Datamart
ctfcore-datamart Mandatory if and only if you install etl datamart Datamart database
cliserver Mandatory NA CLI Server
subversion Optional subversion SVN Version Control
gerrit Optional gerrit Git/Gerrit Version Control
gerrit-database Mandatory if and only if you install gerrit NA (added in TeamForge 17.1) Database for Git/Gerrit. In a distributed setup, add this identifier to the server where you want to run Gerrit database.

In a distributed setup with multiple Git integration servers, add this identifier to all the servers that run the Git databases. For more information, see host:SERVICES token.
binary Optional Optional Artifact repository integration
binary-database Mandatory if and only if you install binary binary Database for artifact repository integration. Binary app (binary) and database (binary-database) have to be installed on the same server.
reviewboard Optional reviewboard Review Board code review tool
reviewboard-database Mandatory if and only if you install reviewboard NA (added in TeamForge 17.1) Database for Review Board. In a distributed setup, add this identifier to the server where you want to run Review Board database.
reviewboard-adapter Mandatory if and only if you install reviewboard NA Adapter for reviewboard to copy ctfrbevents.jar. In a distributed setup, reviewboard-adapter must always be installed on the TeamForge Application Server.
baseline Optional NA Baseline service. In a distributed setup, add this identifier to the server where you want to run the Baseline application.
baseline-database Mandatory if and only if you install baseline NA Baseline database service. In a distributed setup, add this identifier to the server where you want to run the Baseline database.
baseline-post-install Mandatory if and only if you install baseline NA Baseline service that is used to synchronize user information between the Baseline and TeamForge databases.
webr Mandatory. The WEBR application is installed by default when you install or upgrade to TeamForge. NA Webhooks-based Event Broker service that is used to push the messages of specific events received from a Publisher to a Subscriber.
webr-database Mandatory. NA Database service for the TeamForge Webhooks-based Event Broker.

These service identifiers are used in the site-options.conf file’s host:SERVICES token. For more information, see host:SERVICES token.

In addition, installing TeamForge with service-specific FQDNs (instead of machine-specific host/domain names) is highly recommended so that you will be able to change the system landscape at a later point in time without having any impact on the URLs (in other words, end users do not have to notice or change anything). For example, you can create FQDNs specifically for services such as Subversion, Git, mail, Codesearch and so on. For more information, see Service-specific FQDNs.

Single Server or Distributed Setup?

If you are installing TeamForge, are you planning to install on a single server or distribute TeamForge services across two or more servers? How are you going to distribute the services?

In the default setup, all services run on the same server as the main TeamForge application. But in practice, only the TeamForge application needs to run on the TeamForge application server. The other services can share that server or run on other servers, in almost any combination.

Assess your own site’s particular use patterns and resources to decide how to distribute your services, if at all. For example, if you anticipate heavy use of your site, you will want to consider running the site database, the source control service, or the reporting engine on separate hardware to help balance the load. For examples on how to distribute TeamForge services, see host:SERVICES token.

In a distributed setup, it is highly recommended to have dedicated servers for TeamForge database and SCM services, as these are the most sought after services in TeamForge. If you are installing TeamForge Baseline, it is always recommended to install it on a separate server.

When you distribute your services on multiple servers, you must do some configuration to handle communication between the services. Verify your basic networking setup. See Set Up Networking for TeamForge.

PostgreSQL or Oracle?

PostgreSQL 11.12 is installed automatically when you install TeamForge 21.2. 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 21.2 supports Oracle server 12c and Oracle client 12c.
  • Oracle express edition is not supported for both client and server.
  • Review Board was tested with PostgreSQL 11.12 only. Review Board with Oracle was not tested.
  • Git integration works only with PostgreSQL. The Git integration uses 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.

Integrations

TeamForge supports integration with a wide array of third party applications such as 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 21.2 with integrations.

Do you have UserFilter in your Gerrit Quality Gates/Review Rules? See: How to verify if you can upgrade to TeamForge—Git integration 20.1 or later?

One-hop Upgrade Compatibility

Though the TeamForge 21.2 installer supports one-hop upgrade from TeamForge 20.3 or later versions, TeamForge 21.2 upgrade instructions, in general, are for upgrading from TeamForge 21.1 (including update releases, if any) to TeamForge 21.2.

There is no support for one-hop upgrade from TeamForge 20.0 or earlier to TeamForge 21.2. You must upgrade your site to TeamForge 20.3 or later and then upgrade to TeamForge 21.2.

Gerrit Upgrade from Version 2.16 to 3.2

Skip this section if you are upgrading from TeamForge 20.3 to 21.0. This is valid if and only if you are upgrading from TeamForge 20.2 or earlier to TeamForge 21.0.

TeamForge 20.3 and later support Gerrit 3.2—a major upgrade that skips two Gerrit versions—3.0 and 3.1 and includes the following note-worthy changes:

  • TeamForge 20.3 (and later) Gerrit is not data-compatible with Gerrit 2.16 or earlier (in other words, not data-compatible with TeamForge 20.0 or earlier). Intermediate data migration to Gerrit 2.16 happens when you upgrade from TeamForge 20.0 or earlier to TeamForge 20.3 (or later). This means that data migration during upgrade takes more than usual time to complete.
  • TeamForge 20.3 (and later) Gerrit is not index-compatible with any previous version. All open reviews are reindexed offline when you upgrade from TeamForge 20.0 or earlier to TeamForge 20.3 (or later). This means that data migration during upgrade takes more than usual time to complete.
  • Orphaned draft comments are cleaned up when you upgrade to TeamForge 20.3 (or later). It is recommended to schedule and run the following Git garbage collection (Git GC) command directly on the All-Users project before you upgrade to TeamForge 20.3 (or later).
    ssh -p 29418 [admin]@[git-server] gerrit gc All-Users --aggressive --show-progress
    
  • Git Protocol v2 is now default
  • ReviewDB and Gerrit GWT UIs are no longer available
  • For more information about Git protocol v2, see the documentation for Git Protocol v2.
  • ReviewDB removal means that the database backend for changes, accounts, groups and projects (ReviewDb) is removed and this metadata is now stored in git (“NoteDb”). As NoteDb is being used by TeamForge 19.0 and later, this change is seamless for the users.
  • However, the Gerrit GWT UI has more visible consequences. The GWT-related UI plugin functionality had to be ported—either to the new Gerrit Polymer UI or to the TeamForge UI.
Noteworthy Changes
The Gerrit UI has a new look and feel with the new Gerrit Polymer UI replacing the GWT UI.
The Gerrit UI no longer has the history protection tab. This functionality is now available via the TeamForge Code Browser UI.
Gerrit internal repositories are exposed at the integration level in TeamForge.
Microsoft Internet Explorer 11 is no longer supported in Gerrit UI.

Hardware and Backup

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.

While upgrading to a latest TeamForge version, you can choose to upgrade on the same hardware or on new hardware. In general, it is good to have a backup plan in place. Same hardware upgrades need no backup. However, it’s recommended to take a back up as a measure of caution. See Back up and Restore TeamForge for more information.

TeamForge License Framework

The TeamForge license framework has been revamped in TeamForge 21.1.

The new TeamForge license model consists of the following license types:

  • TeamForge ALM Pro
  • TeamForge ALM Essentials
  • TeamForge SCM

Here’s the list of changes to the new TeamForge license model.

  • The Version Control, Collaboration, and Trackers license types are no longer available in TeamForge 21.1 and later
  • The ALM and Baselines license types are bundled together and are being offered as the new TeamForge ALM Pro license
  • The SCM license type has been renamed as TeamForge SCM

When you migrate from TeamForge 21.0 or earlier to TeamForge 21.1 or later:

  • Existing ALM licenses are migrated to TeamForge ALM Pro
  • Existing SCM licenses are migrated to TeamForge SCM
  • All other types of licenses such as Baselines, Version Control, Tracker, and Collaboration are deleted

For more information, see TeamForge License.

Other Dos and Don’ts

Here’s a list of dos, don’ts and points to remember when you install or upgrade TeamForge.

Dos

  • Understand TeamForge installation requirements and plan your installation or upgrade.
  • Get your TeamForge license key and keep it handy.
  • Verify your basic networking setup before installing or upgrading TeamForge. See Set Up Networking for TeamForge.
  • Look for new or modified site-options.conf tokens and update your site-options.conf file as required during the upgrade process. See Site Options Change Log.
  • Set up a TeamForge Stage Server before you upgrade your Production Server.
  • Stop TeamForge services on all servers in a distributed setup while upgrading to TeamForge 21.2.
  • Uninstall hot fixes and add-ons, if any, before you start the TeamForge 21.2 upgrade procedure.
  • As a result of changes to the logging framework in Java 9, the PrintGCDetails and PrintGCTimeStamps logging options are no longer supported. Remove these options from the following tokens while upgrading to TeamForge 18.1 or later. TeamForge provision fails otherwise.

    • JBOSS_JAVA_OPTS
    • PHOENIX_JAVA_OPTS
    • INTEGRATION_JAVA_OPTS
    • ETL_JAVA_OPTS
    • ELASTICSEARCH_JAVA_OPTS

Don'ts

  • Do not customize your operating system installation. Select only the default packages list.
  • While upgrading TeamForge, whether in place or on new hardware, always reuse the old site-options.conf file and make changes as necessary. Do not try to start with a new site-options.conf file. Reusing the old site-options.conf avoids many potential problems, particularly around the management of usernames and passwords.
  • Do not manually modify TeamForge-managed site option tokens such as the AUTO_DATA token. See AUTO_DATA for more information.
  • If you are creating symlinks, note that you must create symlinks only to the TeamForge data directory (/opt/collabnet/teamforge/var). You should not create symlinks to TeamForge application directories (such as /opt/collabnet).

Points to Remember

  • Installing or upgrading TeamForge needs root privileges. You must log on as root or use a root shell to install or upgrade TeamForge.
  • SSL is enabled by default and a self-signed certificate is auto-generated. However, you can use a few site-options.conf tokens to adjust this behavior. To generate the SSL certificates, see Generate SSL Certificates.
  • For the ETL service to run as expected in a distributed TeamForge installation, all servers must have the same time zone.
  • If you have Git integration on a separate server, both TeamForge and Git servers must have their time and date synchronized. Similarly, if Subversion is on a separate server, both TeamForge and Subversion servers must have their time and date synchronized.
  • It’s highly recommended that you install the TeamForge Baseline services on a separate server as the baselining process can consume considerable CPU and database resources. For more information, see Install TeamForge in a Distributed Setup.
  • No backup is required for same hardware upgrades. However, you can create a backup as a measure of caution. See Back up and Restore TeamForge for more information.
  • Always use compatible JDBC drivers meant for specific database versions. See JDBC Drivers Reference for more information. Also see: Why do ETL jobs fail post TeamForge upgrade?
  • You can run the initial load job any time after the installation of TeamForge. We recommend that you run it before you hand over the site to the users. For more information, see ETL Initial Load Jobs.
  • SOAP50 APIs and event handlers are no longer supported in TeamForge 16.10 and later. Use the latest TeamForge SOAP/REST APIs.
  • TeamForge 21.2 installer expects the system locale to be LANG=en_US.UTF-8. TeamForge create runtime (teamforge provision) fails otherwise.
  • Installing TeamForge with service-specific FQDNs (instead of machine-specific host/domain names) is highly recommended so that you will be able to change the system landscape at a later point in time without having any impact on the URLs (in other words, end users do not have to notice or change anything). For example, you can create FQDNs specifically for services such as Subversion, Git, mail, Codesearch and so on. For more information, see Service-specific FQDNs.
  • All such service-specific FQDNs must belong to a single sub domain and it is recommended to create a new sub domain for TeamForge.
  • If you are using service-specific FQDNs
    • A wildcard SSL cert is required. SNI SSL cert cannot be used.
    • When SSL is enabled and no custom SSL certificates are provided, a self-signed wildcard cert is generated for the sub domain.
    • When SSL is enabled and a custom SSL certificate is provided, the CN of the certificate is verified to be a wildcard CN.
  • The ability to run separate PostgreSQL instances for TeamForge database and datamart on the same server is being deprecated in TeamForge 17.11. If you have TeamForge database and datamart on separate PostgreSQL instances on the same server and if you are upgrading on a new hardware, you must Create a Single Cluster for Both Database and Datamart while upgrading to TeamForge 17.11 or later.
  • While upgrading TeamForge-Git integration servers, it is important that Git master and slave servers are upgraded to the same version of TeamForge-Git integration. On sites with Git Replica Servers, you must upgrade the Git Replica Servers first and then upgrade the master Git servers.
  • From TeamForge 19.3, TeamForge Webhooks-based Event Broker is installed automatically when you install/upgrade TeamForge. In other words, you don’t have to run the command yum install teamforge-webr separately.
  • Call back URLs registered with WEBR are lost when you restart WEBR. This means, a TeamForge/Jboss restart must follow immediately after you stop or restart WEBR.
  • TeamForge supports Monit for monitoring services and recovering failed services. Monit is installed on the TeamForge Application server to monitor the health of services and restart the services when they fail. Monit log file is located at /opt/collabnet/teamforge/log/monit/monit.log.