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, Git/Gerrit 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.
  • EventQ is a TeamForge capability that provides traceability for product life cycle activities such as work items, SCM commits, continuous integration (CI) builds, and code reviews.

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
cvs Optional cvs CVS 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.
eventq Mandatory NA (added in TeamForge 17.4) EventQ application server. In a distributed setup, add this identifier to the server where you want to run EventQ application.
redis Mandatory NA (added in TeamForge 17.4) EventQ in-memory database/data structure server. In a distributed setup, add this identifier to the server where you want to run EventQ application.
mongodb Mandatory NA (added in TeamForge 17.4) EventQ database server. In a distributed setup, add this identifier to the server where you want to run EventQ database.
rabbitmq Mandatory NA (added in TeamForge 17.4) EventQ AMQP message server. In a distributed setup, add this identifier to the server where you want to run EventQ message queue.

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.

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

PostgreSQL or Oracle?

PostgreSQL is installed automatically when you install TeamForge. 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.

PostgreSQL 9.6.5 is installed automatically when you install TeamForge 18.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 18.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.6.5 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 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 18.1 with integrations.

One-hop Upgrade Compatibility

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

During an upgrade, the TeamForge 18.1 migration script detects the TeamForge version you run, checks if it’s TeamForge 16.3 or later, and if true, proceeds with the data migration. The migration script aborts with an error message if it detects TeamForge versions older than TeamForge 16.3. You must upgrade your site to TeamForge 16.3 or later and then upgrade to TeamForge 18.1.

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 shoose 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.

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 18.1.
  • Uninstall hot fixes and add-ons, if any, before you start the TeamForge 18.1 upgrade procedure.
  • TeamForge 18.1 supports Java 9. 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.

    • JBOSS_JAVA_OPTS
    • PHOENIX_JAVA_OPTS
    • INTEGRATION_JAVA_OPTS
    • ETL_JAVA_OPTS
    • ELASTICSEARCH_JAVA_OPTS

    TeamForge provision fails on sites that use these options post TeamForge 18.1 upgrade.

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.
  • While you can run both EventQ and TeamForge on the same server, CollabNet recommends such an approach only for testing purposes. It’s always recommended to run EventQ on a separate server for optimal scalability.
  • 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 18.1 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 be long 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.
  • You cannot have a separate PUBLIC_FQDN for EventQ.
  • 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.