Plan your installation/upgrade

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.

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 mandator and some are optional. You can install the services, all in one single server, or distribute them across two or more servers.

Service Name and site-options.conf syntax changes

The names of some of the TeamForge services have been renamed in TeamForge 17.1. In addition, the site-options.conf syntaxes for defining the TeamForge services running on a host (host:SERVICES token) and TeamForge domain name (host:PUBLIC_FQDN token) have been changed in TeamForge 17.1.

Unless otherwise notified, to ensure backward compatibility, TeamForge 17.1 and later versions support both old and new syntaxes for defining your host and domain tokens. Similarly, TeamForge 17.8 supports both old and new service names. However, it is recommended to adjust your site-options.conf in line with these changes as support for older syntax and naming convention would be dropped in due course.

Here's a list of available TeamForge services.

Services Mandatory/Optional Old Name Description
ctfcore Mandatory app Main TeamForge application server
search Mandatory indexer Indexing and Searching
mail Mandatory NA Email server
ctfcore-database Mandatory database 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
subversion Optional subversion SVN Version Control
cvs Optional cvs CVS Version Control
gerrit Optional gerrit Git/Gerrit Version Control
gerrit-database Mandatory if and if only if you install gerrit NA Database for Git/Gerrit. In a distributed setup, add this identifier on the server where you want to run Gerrit database.
gerrit-database-performance Automatically installed if you install gerrit NA It is a second database that Gerrit uses to cache data.
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 installed on the same server.
reviewboard Optional reviewboard Review Board code review tool
reviewboard-database Mandatory if and only if you install reviewboard NA Database for Review Board. In a distribute setup, add this identifier on the server where you want to run Review Board database.
reviewboard-adapter Mandatory if and only if you install reviewboard NA Adapter for Review Board. In a distribute setup, reviewboard-adapter must always be installed on the TeamForge Application Server.
eventq Mandatory NA EventQ application server. In a distributed setup, add this identifier on the server where you want to run EventQ application.
redis Mandatory NA EventQ in-memory database/data structure server. In a distributed setup, add this identifier on the server where you want to run EventQ application.
mongodb Mandatory NA EventQ database server. In a distributed setup, add this identifier on the server where you want to run EventQ database.
rabbimq Mandatory NA EventQ AMQP message server. In a distributed setup, add this identifier on 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.

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.

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 9.6.3 is installed automatically when you install TeamForge 17.8. 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:
  • TeamForge17.8 supports Oracle server 12c and Oracle client .
  • Oracle express edition is not supported for both client and server.
  • Review Board 2.5.6.1 was tested with PostgreSQL 9.6.3 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.

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

One-hop upgrade compatibility

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

During an upgrade, the TeamForge 17.8 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 7.2 or earlier versions. You must upgrade your site to TeamForge 16.3 or later and then upgrade to TeamForge 17.8.

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 Backup and Restore TeamForge and EventQ 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.
  • Understand TeamForge installation requirements.
  • Get your TeamForge license key and keep it handy.
  • Installing or upgrading TeamForge needs root privileges. You must log on as root or use a root shell to install or upgrade TeamForge.
  • Verify your basic networking setup before installing or upgrading TeamForge. See Set up Networking for 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.
  • Do not customize your operating system installation. Select only the default packages list.
  • You need to add the SSL certificate to the Java keystore if the site uses a self-signed certificate. For instructions on adding the self-signed certificate to the Java keystore, see Protect Integrations with SSL.
  • 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.
  • 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.
  • Do not manually modify TeamForge-managed site option tokens such as the AUTO_DATA token. See . for more information.
  • No backup is required for same hardware upgrades. However, you can create a backup as a precaution. See Backup and Restore TeamForge and EventQ 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 When do I run the initial load job?
  • 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 17.8.
  • If installed, stop DevOps Lifecycle Manager (DLM) services too while upgrading to TeamForge 17.8:
    • systemctl stop actionhubserver
    • systemctl stop actionhubdaemon
  • Uninstall hot fixes and add-ons, if any, before you start the TeamForge 17.8 upgrade procedure.
  • SOAP50 APIs and event handlers are no longer supported in TeamForge 17.1and later. Use the latest TeamForge SOAP/REST APIs.

What's new in TeamForge 17.8 install / upgrade