Skip to main content
Version: TeamForge 23.0

Upgrade TeamForge on New Hardware with All Services on a Single Server

In this single server setup, the following TeamForge services run on the TeamForge Application Server (server-01).

  • TeamForge Application Server (ctfcore)
  • Database Server (ctfcore-database and ctfcore-datamart)
  • Codesearch Server (codesearch)
  • Mail Server (mail)
  • ETL Server (etl)
  • Git Integration Server (gerrit and gerrit-database)
  • SCM Integration Server (subversion)
  • Search Server (search).
  • TeamForge CLI Server (cliserver)
  • Review Board (reviewboard, reviewboard-database, reviewboard-adapter)1
  • CLI Server (cliserver)
  • TeamForge Baseline (baseline, baseline-database, baseline-post-install)2
  • TeamForge Webhooks-based Event Broker (webr, webr-database)
  • Service Monitor (service-monitor)

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

One-hop Upgrade Compatibility​

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

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

Before You Begin—Generate New TeamForge License

TeamForge has a new licensing framework starting from TeamForge 21.1. If you are upgrading from TeamForge 21.0 or earlier to TeamForge 21.1 or later, you must get the new TeamForge license and add it to your site before upgrading to TeamForge 21.1 or later. Contact Digital.ai Support to get the new TeamForge license for your site before you run the teamforge provision command. The teamforge provision command fails otherwise.

Before You Begin—CVS End-of-Life

CVS is no longer supported by TeamForge 20.2 and later. You must migrate your CVS repositories to any of the other supported SCM tool (Git/SVN for example) when you upgrade to TeamForge 20.2 or later.

  1. Undeploy CVS on the TeamForge SCM server that runs CVS. Do this after you stop the TeamForge services while upgrading to TeamForge 20.2 or later versions on the same hardware. Skip this step in case of new hardware upgrades.

    teamforge undeploy -s cvs

  2. Remove cvs from the host:SERVICES token of the site-options.conf file (on all the TeamForge servers), failing which the teamforge provision command aborts with an error.

Before You Begin—EventQ End-of-Life

EventQ as a TeamForge service is no longer supported and is completely removed from TeamForge 20.0 (and later). There are a few things to consider in case you have been using EventQ and are upgrading to TeamForge 20.0 or later. For more information, see EventQ End of Life.

Before You Begin—chmod /svnroot

Do this before you stop TeamForge while upgrading to TeamForge 18.2 or later versions.

Get value of SUBVERSION_REPOSITORY_BASE from the /opt/collabnet/teamforge/runtime/conf/runtime-options.conf file of your existing TeamForge server and run the following command:

chmod -R 775 $SUBVERSION_REPOSITORY_BASE

Where $SUBVERSION_REPOSITORY_BASE is the path to the /svnroot directory.

This is required to work around the unusually long time taken to migrate the Subversion data during the first run of the teamforge provision command.

Prepare the New TeamForge Application Server (server-01)​

  1. Install RHEL 8.6 and log on as root.

    The host must be registered with the Red Hat Network if you are using Red Hat Enterprise Linux.
    See the RHEL 8.6 Installation Guide for help.

  2. Check your networking setup. See Set up Networking for more information.

Install the TeamForge Services​

  1. Install TeamForge.

    yum install teamforge

Install Monit.

important

If you haven't already installed the latest version of the Monit application, download it here.

  1. Download Monit for

    • RHEL 8.x from the EPEL repository.

      wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
      rpm -ivh epel-release-latest-8.noarch.rpm

    • RHEL/CentOS 7.x from the EPEL repository.

      wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
      rpm -ivh epel-release-latest-7.noarch.rpm

  2. Install Monit.

    yum install monit

Install the Baseline packages.

yum install teamforge-baseline

Back up and Restore TeamForge Database, Data Directories and site-options.conf​

See Back up and Restore TeamForge Database, Data Directories and site-options.conf.

Back up and Restore the Review Board Database and Data Directories​

See Back up and Restore Review Board.

Disable OID While Upgrading to TeamForge 22.0 or later​

Do this if you are upgrading from TeamForge 21.2 or earlier to TeamForge 22.0 or later.

TeamForge 22.0 supports PostgreSQL 13.4 . As a result, you must run the /opt/collabnet/teamforge/dist/scripts/disable_oid_pg_upgrade13.py script to disable the object identifiers (OIDs) before provisioning TeamForge services.

/opt/collabnet/teamforge/dist/scripts/disable_oid_pg_upgrade13.py

Import the SSL Certs to the Java Keystore​

Do this on the TeamForge Application Server (server-01).

  1. Locate the Java keystore.

    This is PATH_TO_JAVA/jre/lib/security/cacerts. For example, this may be /usr/local/j2sdk1.4.2_10/jre/lib/security/cacerts.

  2. Locate the Java keytool utility.

    This is PATH_TO_JAVA/bin/keytool For example, /usr/local/j2sdk1.4.2_10/bin/keytool.

  3. Import the certificate into the keystore.

    PATH_TO_JAVA/bin/keytool -import -keystore PATH_TO_JAVA/jre/lib/security/cacerts -file <server>.crt -alias <server>
    note

    Any value is accepted for server in -alias <server>.

Configure the New TeamForge Application Server (server-01)​

Log on to the TeamForge Application Server (server-01) and set up the site-options.conf file.

  1. Copy the site-options.conf file to the TeamForge installer directory.

    cp /tmp/site-options.conf /opt/collabnet/teamforge/etc/

  2. Set up your site's master configuration file.

    important

    See Site Options Change Log for a list of site option changes. While upgrading to a latest TeamForge release, make sure that obsolete site option tokens, if any, are removed from the site-options.conf file of the TeamForge version you are upgrading to.

    vi /opt/collabnet/teamforge/etc/site-options.conf

    host:SERVICES Token​

    server-01:SERVICES = ctfcore ctfcore-database ctfcore-datamart service-monitor mail etl search codesearch subversion cliserver gerrit gerrit-database binary binary-database reviewboard reviewboard-database reviewboard-adapter baseline baseline-database baseline-post-install webr webr-database

    host:PUBLIC_FQDN Token​

    server-01:PUBLIC_FQDN = my.app.domain.com

    Save the site-options.conf file.

    For further customization of your site configuration (SSL settings, password policy settings, PostgreSQL settings, LDAP settings and so on):

Generate the License Key​

As you are upgrading on new hardware, contact Digital.ai Support, generate the license key for the new server (IP address) and use it to replace /opt/collabnet/teamforge/var/etc/sflicense.txt.

If you have the TeamForge database and datamart on two separate ports on the same server, see Create a Single Cluster for Both Database and Datamart.

Provision Services​

TeamForge 16.10 and earlier versions use Oracle JDK. As TeamForge 19.2 and later use OpenJDK, the TeamForge installer checks if Oracle JDK is present when you upgrade to TeamForge 19.2 or later—and if found—would error out when you provision TeamForge. You must uninstall Oracle JDK and proceed.

Run the following command to uninstall Oracle JDK:

rpm -e jdk1.8.0_74-1.8.0_74-fcs.x86_64

  1. Provision services.

    teamforge provision

    TeamForge 23.0 installer expects the system locale to be LANG=en_US.UTF-8. TeamForge create runtime (teamforge provision) fails otherwise.

Delete Existing Elastic Search Indexes While Upgrading to TeamForge 22.0 or later​

TeamForge 22.0 uses Elastic Search 7.16.3 to address the Log4j dependent vulnerabilities. As a result, you must delete the existing Elastic Search indexes as they might not be compatible with Elastic Search 7.16.3. The Elastic Search service would fail in this case. Use the /opt/collabnet/teamforge/runtime/scripts/delete_es_nodes.py script to delete the existing indexes. You must restart the Elastic Search service after deleting the old indexes. For more information, see TeamForge upgrade instructions.

While the existing ELASTICSEARCH_JAVA_OPTS token is still supported to configure the JAVA_OPTS values, the following tokens have been added to configure the minimum and maximum heap size for Elastic Search.

  • ELASTICSEARCH_MIN_HEAP_SIZE=-Xms2g
  • ELASTICSEARCH_MAX_HEAP_SIZE=-Xmx2g

In other words, in TeamForge 21.2 and earlier, you just had to configure ELASTICSEARCH_JAVA_OPTS=-Xms2g -Xmx2g -Dlog4j2.formatMsgNoLookups=true.

Whereas, in TeamForge 22.0 and later, you must configure:

  • ELASTICSEARCH_MIN_HEAP_SIZE=-Xms2g
  • ELASTICSEARCH_MAX_HEAP_SIZE=-Xmx2g
  • ELASTICSEARCH_JAVA_OPTS=-Dlog4j2.formatMsgNoLookups=true

Finishing Tasks​

  1. Verify TeamForge upgrade.

    1. Reboot the server and make sure all services come up automatically at startup.
    2. Log on to the TeamForge web application using the default Admin credentials.
      • Username: admin
      • Password: admin
    3. If your site has custom branding, verify that your branding changes still work as intended. See Customize TeamForge.
    4. Let your site's users know they've been upgraded. See Create a Site-wide Broadcast.
  2. Remove the backup files, if any, after the TeamForge site is up and running as expected. Remove the repository and the file system backup from the /tmp/backup_dir directory.

Post Upgrade Tasks​

Also See...​

Footnotes​

  1. TeamForge 23.0 supports Review Board 4.0.6 on RHEL 8.6 and Review Board 4.0.6 on RHEL/CentOS 7.9. ↩

  2. It's highly recommended that you install/upgrade the TeamForge Baseline services on a separate server as the baselining process can consume considerable CPU and database resources. For more information, see Upgrade TeamForge on New Hardware in a Distributed Multi-host Setup. ↩