Upgrade TeamForge on the Same Hardware with Oracle Database

In this setup, TeamForge, Oracle database and other services are distributed across three servers, server-01 through server-03 as illustrated in the following table.

You can install TeamForge on both RHEL/CentOS 7.9 and 6.10. In this distributed setup, all the following services are installed on RHEL/CentOS 7.9 servers.

Dos and Don’ts

chmod -R 775 $SUBVERSION_REPOSITORY_BASE

Back up Your Oracle Database

• See Oracle Database Backup and Recovery User’s Guide
• See Oracle Database Backup and Recovery FAQ

Uninstall Custom Event Handlers, Hot Fixes and Add-ons

Log on to the TeamForge Application Server.

1. SOAP 50 is no longer supported. Back up all your custom event handlers and remove all the event handler JAR files before starting your TeamForge upgrade process.
   1. Go to My Workspace > Admin.
   2. Click System Tools from the Projects menu.
   3. Click Customizations.
   4. Select the custom event handler and click Delete.
      Tip: Post upgrade, you can add custom event handlers again from the backup while making sure that you don’t have SOAP50 (deprecated) library used.
2. Uninstall hotfixes and add-ons, if any, installed on your site.

yum upgrade

1. Stop TeamForge.

   Important: Stop TeamForge on all the servers in a distributed setup.

   teamforge stop
   

2. Upgrade the operating system packages.

   yum upgrade
   

   Note: Run yum upgrade on all the servers.

Configure the TeamForge Installation Repository

1. Configure the TeamForge installation repository.

   TeamForge Installation Repository Configuration for Sites with Internet Access

   1. Contact the CollabNet Support and download the TeamForge 20.3 installation repository package to /tmp.
   2. Install the repository package.

      yum install -y /tmp/collabnet-teamforge-repo-20.3-0-noarch.rpm
      

   3. Refresh your repository cache.

      yum clean all
      

   TeamForge Installation Repository Configuration for Sites without Internet Access

   1. Contact the CollabNet Support to get the auxiliary installer package for TeamForge 20.3 disconnected installation and save it in /tmp.
      • RHEL/CentOS 6.10 64 bit: CTF-Disconnected-media-20.3.398-677.rhel6.x86_64.rpm
      • RHEL/CentOS 7.9 64 bit: CTF-Disconnected-media-20.3.398-677.rhel7.x86_64.rpm
      • In addition to the above CentOS 7.9 64 bit RPM package, you must get the following CentOS 7.9 compatibility RPM, which is required for TeamForge 20.3 disconnected media installation on CentOS 7.9 profile: compat-ctf-dc-media-1.2-1.el7.noarch.rpm.
   2. Unpack the disconnected installation package.

      rpm -Uvh <package-name>
      

   3. Unpack the compat-ctf-dc-media-1.2-1.el7.noarch.rpm package if you are installing TeamForge 20.3 on CentOS 7.9.

      rpm -ivh compat-ctf-dc-media-1.2-1.el7.noarch.rpm
      

   4. If you are installing TeamForge 20.3 on RHEL/CentOS 6.10, contact the CollabNet Support to get the python-modules-sources-el6.zip file and unzip it to /opt/collabnet/teamforge/service/reviewboard/resources/SOURCES/python-modules-sources.

         unzip python-modules-sources-el6.zip -d /opt/collabnet/teamforge/service/reviewboard/resources/SOURCES/python-modules-sources
      

      If you are installing TeamForge 20.3 on RHEL/CentOS 7.9, contact the CollabNet Support to get the python-modules-sources-el7.zip file and unzip it to /opt/collabnet/teamforge/service/reviewboard/resources/SOURCES/python-modules-sources.

         unzip python-modules-sources-el7.zip -d /opt/collabnet/teamforge/service/reviewboard/resources/SOURCES/python-modules-sources
      

   5. If not mounted already, mount the RHEL/CentOS installation DVD.

      The DVD contains the necessary software and utilities required for installing TeamForge without internet access. In the following commands, replace “cdrom” with the identifier for your server’s CD/DVD drive, if necessary.

      cd /media/
      mkdir cdrom
      mount /dev/cdrom ./cdrom/
      

      If there are any spaces in the automount, unmount it first and mount it as a filepath, with no spaces.

   6. Create a yum configuration file that points to the RHEL/CentOS installation DVD.

      vi /etc/yum.repos.d/cdrom.repo
      

      Here’s a sample yum configuration file.

      [RHEL-CDROM]
      name=RHEL CDRom 			
      baseurl=file:///media/cdrom/Server/
      gpgfile=file:///media/cdrom/RPM-GPG-KEY-redhat-release 
      enabled=1
      gpgcheck=0
      

   7. Verify your yum configuration files.

      yum list httpd
      yum list apr
      

Upgrade the TeamForge Services

1. Upgrade the TeamForge and Review Board application services on the TeamForge Application Server (server-01).

   Before You Begin

   If you are installing TeamForge 20.3 on RHEL/CentOS 6.10, contact CollabNet Support to get the python-modules-sources-el6.zip file and unzip it to /opt/collabnet/teamforge/service/reviewboard/resources/SOURCES/python-modules-sources.

   unzip python-modules-sources-el6.zip -d /opt/collabnet/teamforge/service/reviewboard/resources/SOURCES/python-modules-sources
   

   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/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
        

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

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

   2. Install Monit.

       yum install monit
      

Back up the TeamForge Data Directories

On sites running TeamForge 16.7 or earlier versions:

1. Back up the following data directories.
   Tip: In a distributed setup, you must backup specific directories such as /svnroot and /cvsroot from the server that hosts those SCM services.
   Note: CVS is no longer supported by TeamForge 20.2 (and later). Backing up and restoring the /cvsroot is recommended, but optional though.

   Directory	Contents
   /opt/collabnet/teamforge/var	User-created data, such as artifact attachments
   /opt/collabnet/reviewboard	Review Board data
   /svnroot	Subversion source code repositories
   /sf-svnroot	Subversion repository for branding data
   /cvsroot	CVS source code repositories (required only if you have CVS)
   /gitroot	Git source code repositories

   cp -Rpf /svnroot /sf-svnroot /cvsroot /gitroot /opt/collabnet/teamforge/var /opt/collabnet/reviewboard /tmp/backup_dir
   

2. Back up the /opt/collabnet/gerrit directory if you have Git integration.
   Tip: Do this on the server that hosts the TeamForge-Git integration services.

   mkdir /tmp/backup_dir/gerrit
   cp -Rpfv /gitroot /tmp/backup_dir
   cp -Rpfv /opt/collabnet/gerrit/ /tmp/backup_dir/gerrit
   

On sites running TeamForge 16.10 or later versions:

1. Back up the /opt/collabnet/teamforge/var directory.
   Tip: Do this on both the TeamForge Application and Database servers in case you have them running on two separate servers.

   mkdir -p /tmp/backup_dir
   cp -Rpfv /opt/collabnet/teamforge/var /tmp/backup_dir
   

2. Back up the /opt/collabnet/gerrit directory if you have Git integration.
   Tip: Do this on the server that hosts the TeamForge-Git integration services.

   mkdir /tmp/backup_dir/gerrit
   cp -Rpfv /opt/collabnet/gerrit/ /tmp/backup_dir/gerrit
   

Back up and Restore Review Board Database and Data Directories

See Back up and Restore Review Board Database and Data Directories

Set up the site-options.conf File and Provision Services

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

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

   host:SERVICES Token

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

   host:PUBLIC_FQDN Token

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

   Configure the Oracle Database Tokens

   Configure the Oracle database name, usernames and passwords as configured on the Oracle Database Server.

   • Database type is oracle (DATABASE_TYPE=oracle)
   • Database service name is the host name of the Oracle Database Server (for example, DATABASE_SERVICE_NAME=cu349.maa.collab.net)
   • Reports database service name is the host name of the server where the datamart is (for example, REPORTS_DATABASE_SERVICE_NAME=cu349.maa.collab.net)

   DATABASE_TYPE=oracle
   
   # Adjust usernames/passwords to match what has been configured on the database server.
   DATABASE_USERNAME=ctfuser
   DATABASE_PASSWORD=ctfpwd
   DATABASE_READ_ONLY_USER=ctfrouser
   DATABASE_READ_ONLY_PASSWORD=ctfropwd
   DATABASE_NAME=orcl
   DATABASE_SERVICE_NAME=
   ​
   # Adjust usernames/passwords to match what has been configured on the database server.
   REPORTS_DATABASE_USERNAME=ctfrptuser
   REPORTS_DATABASE_PASSWORD=ctfrptpwd
   REPORTS_DATABASE_NAME=orcl
   REPORTS_DATABASE_READ_ONLY_USER=ctfrptrouser
   REPORTS_DATABASE_READ_ONLY_PASSWORD=ctfrptropwd
   REPORTS_DATABASE_SERVICE_NAME=
   

   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): Site options configuration contd…

   SSL Tokens

   SSL is enabled by default and a self-signed certificate is auto-generated. Use the following tokens to adjust this behavior.

   Note: TeamForge runs only with SSL from TeamForge 19.2. Hence the site-options.conf token option SSL=off is not supported any more. TeamForge provision fails and throws an error, if SSL is set to off.

   SSL_CERT_FILE=
   SSL_KEY_FILE=
   SSL_CHAIN_FILE=
   

   • To generate the SSL certificates, see Generate SSL certificates.
   • Have the custom SSL certificate and private key for custom SSL certificate in place and provide their absolute paths in these tokens. SSL_CHAIN_FILE (intermediate certificate) is optional.

   Password Tokens

   • TeamForge 7.1 and later support automatic password creation. See AUTO_DATA for more information.

   • Set the REQUIRE_PASSWORD_SECURITY token to true to enforce password security policy for the site.

     If the token REQUIRE_PASSWORD_SECURITY is enabled, then set a value for the token, PASSWORD_CONTROL_EFFECTIVE_DATE.

     Warning: The Password Control Kit (PCK) disables, deletes or expires user accounts that don’t meet the password security requirements starting from the date set for the PASSWORD_CONTROL_EFFECTIVE_DATE token. If a date is not set, the PCK disables, deletes or expires user accounts immediately. See PASSWORD_CONTROL_EFFECTIVE_DATE for more information.

     You can also set the following tokens to enforce a more stricter password policy:

     • MINIMUM_PASSWORD_LENGTH
     • MAX_PASSWORD_LENGTH
     • PASSWORD_REQUIRES_NUMBER
     • PASSWORD_REQUIRES_NON_ALPHANUM
     • PASSWORD_REQUIRES_MIXED_CASE
     • REQUIRE_PASSWORD_SECURITY
     • LOGIN_ATTEMPT_LOCK
     • PASSWORD_HISTORY_AGE
     • ALLOW_PASSWORD_DICTIONARY_WORD
   • If the token REQUIRE_RANDOM_ADMIN_PASSWORD is already set to true, then set the token ADMIN_EMAIL with a valid email address.

       ADMIN_EMAIL=root@{__APPLICATION_HOST__}
     

   • If you have LDAP set up for external authentication, you must set the REQUIRE_USER_PASSWORD_CHANGE site options token to false.

   Prevent Cross-site Scripting

   An attacker could potentially upload an HTML page to TeamForge that contains active code, such as JavaScript. This active code would then be executed by clients’ browsers when they view the page, which can harm the system.

   To prevent an attack of this sort, you can specify whether or not HTML code is displayed in TeamForge. This flag applies to all documents, tracker, task, and forum attachments, and files in the file release system.

   Set the SAFE_DOWNLOAD_MODE token according to your requirements. For more information, see SAFE_DOWNLOAD_MODE.

   JAVA_OPTS

   Configure the JBOSS_JAVA_OPTS site-options.conf token. See JBOSS_JAVA_OPTS.

   Note: All JVM parameters but -Xms1024m and -Xmx2048m have been hard-coded in the TeamForge core application. You need not manually configure any other parameter (such as -XX:MaxMetaspaceSize=512m -XX:ReservedCodeCacheSize=128M -server -XX:+HeapDumpOnOutOfMemoryError -Djsse.enableSNIExtension=false -Dsun.rmi.dgc.client.gcInterval=600000 -Dsun.rmi.dgc.server.gcInterval=600000) in the site-options.conf file.

   TeamForge 18.1 (and later) 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 upgrade to TeamForge 18.1.

   Save the site-options.conf file.

2. Provision services.

   teamforge provision
   

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

Update the Webhook Events and Create New Webhooks

While TeamForge 19.2 (and earlier) offered simple webhooks support, TeamForge 19.3 (and later) offer pre-submit and post-submit webhooks. New webhook events have been added and webhook event names have been updated as well.

If you are upgrading from TeamForge 19.2 (or earlier) to TeamForge 19.3 (or later), you must truncate the webhook and webhook_event tables on the Oracle database server, insert the new webhook events into the webhook_event table and create new webhooks.

1. Note down the list of webhooks you have before truncating the webhooks table. You may take a screenshot of the webhook configuration just in case.
2. Run the following queries to back up the webhook and webhook_event TeamForge tables.

   create table webhookbackup as select * from webhook;
   create table webhookeventsbackup as select * from webhook_event;
   

3. Truncate the webhook and webhook_event TeamForge tables.

   truncate table webhook;
   truncate table webhook_event;
   

4. Insert the new TeamForge webhook events into the webhook_event table. Run the following queries one-by-one in order on the Oracle database server.

   insert  into  webhook_event  (surrogate_id,webhook_surrogate_id,event_type,  event_type_name)  select  webhook_event_key_seq.nextval,0,'Teamforge.Artifact.Create','TOPIC'    from  dual  where  Not  exists  (select  1  from  webhook_event  where  event_type='Teamforge.Artifact.Create');
   
   insert  into  webhook_event  (surrogate_id,webhook_surrogate_id,event_type,  event_type_name)    select  webhook_event_key_seq.nextval,0,'Teamforge.Artifact.Update','TOPIC'  from  dual  where  Not  exists  (select  1  from  webhook_event  where  event_type='Teamforge.Artifact.Update');
   
   insert  into  webhook_event  (surrogate_id,webhook_surrogate_id,event_type,  event_type_name) select  webhook_event_key_seq.nextval,0,'Teamforge.Artifact.Move','TOPIC'  from  dual  where  Not  exists  (select  1  from  webhook_event  where  event_type='Teamforge.Artifact.Move');
      
   insert  into  webhook_event  (surrogate_id,webhook_surrogate_id,event_type,  event_type_name) select  webhook_event_key_seq.nextval,0,'Teamforge.Artifact.Clone','TOPIC'    from  dual  where  Not  exists  (select  1  from  webhook_event  where  event_type='Teamforge.Artifact.Clone');
      
   insert  into  webhook_event  (surrogate_id,webhook_surrogate_id,event_type,  event_type_name) select  webhook_event_key_seq.nextval,0,'Teamforge.Artifact.Delete','TOPIC'    from  dual  where  Not  exists  (select  1  from  webhook_event  where  event_type='Teamforge.Artifact.Delete');
   
   insert  into  webhook_event  (surrogate_id,webhook_surrogate_id,event_type,  event_type_name) select  webhook_event_key_seq.nextval,0,'Teamforge.Artifact.Create.Presubmit','SYNC'   from  dual  where  Not  exists  (select  1  from  webhook_event   where      event_type='Teamforge.Artifact.Create.Presubmit');
   
   insert  into  webhook_event  (surrogate_id,webhook_surrogate_id,event_type,  event_type_name) select  webhook_event_key_seq.nextval,0,'Teamforge.Artifact.Update.Presubmit','SYNC'   from  dual  where  Not  exists  (select  1  from  webhook_event  where  event_type='Teamforge.Artifact.Update.Presubmit');
   
   insert  into  webhook_event  (surrogate_id,webhook_surrogate_id,event_type,  event_type_name) select  webhook_event_key_seq.nextval,0,'Teamforge.Artifact.Move.Presubmit','SYNC'  from  dual  where  Not  exists  (select  1  from  webhook_event   where  event_type='Teamforge.Artifact.Move.Presubmit');
   
   insert  into  webhook_event  (surrogate_id,webhook_surrogate_id,event_type,  event_type_name) select  webhook_event_key_seq.nextval,0,'Teamforge.Artifact.Clone.Presubmit','SYNC'  from  dual  where  Not  exists  (select  1  from  webhook_event   where  event_type='Teamforge.Artifact.Clone.Presubmit');
   
   insert  into  webhook_event  (surrogate_id,webhook_surrogate_id,event_type,  event_type_name) select  webhook_event_key_seq.nextval,0,'Teamforge.Artifact.Delete.Presubmit','SYNC'  from  dual  where  Not  exists  (select  1  from  webhook_event  where  event_type='Teamforge.Artifact.Delete.Presubmit');
   
   

5. Run the following query to verify the events inserted into the webhook_event table.

   select event_type,  event_type_name from webhook_event;
   

   The output lists the events:

   

Verify TeamForge Upgrade

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

Post Upgrade Tasks

• Run TeamForge in SELinux enabled Mode
• Users are not getting email notifications for review requests and reviews. What should I do?
• Integrate Jenkins, JIRA, and TestLink using the TeamForge Webhooks-based Event Broker

Also See…

• FAQs on Install / Upgrade / Administration