Plan Your Installation / Upgrade

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.
• Baselines 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 Baselines.
• 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.

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.

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.6 is installed automatically when you install TeamForge 20.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 20.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.6 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 20.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 20.2 installer supports one-hop upgrade from TeamForge 19.1 or later versions, TeamForge 20.2 upgrade instructions, in general, are for upgrading from TeamForge 20.1 (including update releases, if any) to TeamForge 20.2.

There is no support for one-hop upgrade from TeamForge 19.0 or earlier to TeamForge 20.2. You must upgrade your site to TeamForge 19.1 or later and then upgrade to TeamForge 20.2.

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.

Other Dos and Don’ts

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