How to set up a TeamForge Stage Server

Whenever a new TeamForge version is released, though not mandatory, it's a best practice to set up a stage server and test the upgrade steps before upgrading your production site to the latest TeamForge version. This topic walks you through the steps required to set up a TeamForge 7.2 stage server that runs on RHEL/CentOS 6.5. It is assumed that:
  • Your site runs TeamForge 7.2 on RHEL/CentOS 6.5.
  • You have Git, Review Board and Black Duck Code Sight running on the same server as TeamForge.
  • You have a new RHEL/CentOS 6.5 server ready to be set up as the stage server.

Though the steps in this topic explicitly talks about TeamForge 7.2, they are valid for setting up the stage server for any later versions of TeamForge. However, you must pay attention to some of the platform specific issues associated with specific TeamForge releases and adjust the following steps accordingly while setting up the stage server.

For example, Black Duck Code Sight (BDCS) 2.1.3 has no support for RHEL/CentOS 7.x. So, if you are setting up a stage server for TeamForge 8.0, which supports RHEL/CentOS 7.0, you might be having your BDCS running on a separate RHEL/CentOS 6.6 server.

In addition, keep in mind that some of the steps required for setting up the TeamForge 7.2 stage server may not be required for later versions of TeamForge. For example, setting up the JAVA_HOME site-options token is required for TeamForge 7.2, but has been automated in TeamForge 8.0 and later. Refer to the upgrade instructions of the TeamForge release in question for more such release-specific steps.

Back up your TeamForge 7.2 production data

  1. Log on to the existing TeamForge 7.2 production server as root.
  2. Stop TeamForge.
    • /etc/init.d/collabnet stop all
  3. Back up your site database.
    • cd /var/lib
    • tar -zcvf pgsql.tgz pgsql
  4. Copy the database backup to the /tmp/backup_dir directory.
    • mkdir -p /tmp/Prod_backup_dir
    • cp -Rpf /var/lib/pgsql.tgz /tmp/Prod_backup_dir
  5. Back up the file system data.
    Note: /tmp/Prod_backup_dir is just an example. You can use any directory or partition you prefer to store your backup files.
    1. Make an archive file with the following data directories:
      • cp -Rpfv /svnroot /sf-svnroot /cvsroot /opt/collabnet/teamforge/var /tmp/Prod_backup_dir
    2. If GIT integration is enabled, do the following:
      • mkdir /tmp/Prod_backup_dir/gerrit
      • cp -Rpfv /gitroot /tmp/Prod_backup_dir
      • cp -Rpfv /opt/collabnet/gerrit/ /tmp/Prod_backup_dir/gerrit
    3. Compress your backup data.
      • cd /tmp
      • tar czvf Prod_backup.tgz Prod_backup_dir
    4. Back up your SSH keys, if any.
    5. Back up your SSL certificates and keys, if any.
  6. Copy the master configuration file from the old server to the /tmp directory on the stage server.
    • scp /opt/collabnet/teamforge-installer/ username@newbox:/tmp
    • 'scp' is just an example. You can choose any file transfer method you prefer.
  7. Copy the file system data to the stage server.
    • scp /tmp/Prod_backup.tgz username@newbox:/tmp
  8. Back up the Review Board data directory.
    • cd /opt/collabnet
    • tar -zcvf /tmp/reviewboard_data.tgz reviewboard
    Copy the /tmp/reviewboard_data.tgz file to the /tmp directory of the stage server.

Set up the new TeamForge 7.2 stage server

  1. Log on to the new TeamForge 7.2 stage server as root.
  2. Unpack the file system data.
    • cd /tmp
    • tar xzvf Prod_backup.tgz
  3. If the TeamForge server has SELinux enabled, run it in 'Permissive' mode temporarily while installing or upgrading TeamForge.
    1. Verify if SELinux is running in enforcing mode.
      • getenforce
    2. If the output of the getenforce command is "Permissive", continue with the next step.
    3. If not, run the following command to bring it to 'Permissive' mode.
      • setenforce 0
  4. Configure your TeamForge 7.2 installation repository. See TeamForge installation repository configuration for Red Hat/CentOS.
  5. Install the following application packages.
    1. TeamForge: To install the TeamForge application packages run the following command:
      • yum install teamforge
    2. GIT: To install the GIT packages run the following command:
      • yum install teamforge-git
    3. Black Duck Code Sight: To install the Black Duck Code Sight packages run the following command:
      • yum install teamforge-codesearch
  6. Reload the PostgreSQL data.
    • cd /var/lib
    • mv pgsql pgsql_orig
    • tar -zxvf /tmp/Prod_backup_dir/pgsql.tgz
  7. Copy the site-options.conf file to the TeamForge installer directory.
    • cp /tmp/site-options.conf /opt/collabnet/teamforge-installer/
  8. In the site-options.conf file, make sure you do the following.
    • vi /opt/collabnet/teamforge-installer/
    1. Update the host name and domain name, if required.
      HOST_localhost=app database datamart etl indexer subversion cvs
      Configure the following settings if you are installing Git.
      HOST_localhost=app database datamart etl indexer subversion cvs gerrit
      Configure the following settings if you are installing Black Duck Code Sight.
      HOST_localhost=app database datamart etl indexer subversion cvs codesearch 
    2. Configure the JAVA_HOME token for TeamForge.
    3. Turn on the SSL for your site by editing the relevant variables in the site-options.conf file. To generate the SSL certificates, see Generate SSL certificates.
      Note: The SSL_CA_CERT_FILE and SSL_CHAIN_FILE are optional.
    4. If your site is running in SSL mode (SSL=on), add the following java runtime property to the JBOSS_JAVA_OPTS token.
      JBOSS_JAVA_OPTS=-Xms1536m -Xmx1536m -XX:MaxPermSize=512m -server -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/tmp -verbose:gc -XX:+
      PrintGCTimeStamps -XX:+PrintGCDetails -Djsse.enableSNIExtension=false -Dsun.rmi.dgc.client.gcInterval=600000 -Dsun.rmi.dgc.server.gcInterval=600000
    5. If the token REQUIRE_PASSWORD_SECURITY is enabled, then set a value for the token, PASSWORD_CONTROL_EFFECTIVE_DATE. 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.
    6. Starting from TeamForge 7.1, the TeamForge installer supports automatic password creation for the following password-related site-options.conf tokens. When set to $auto$, the passwords for the tokens are randomly generated, encrypted and stored in the AUTO_DATA token in the site-options.conf file. This feature is enabled by default. You can, however, override any of the following password-related tokens with the password of your choice.
      MIRROR_DATABASE_PASSWORD (applicable only if you are mirroring your database)
    7. Password Obfuscation

      The password obfuscation is enabled by default. As a result, all password-related tokens are encrypted in all the TeamForge configuration files.

      Important: The password-related tokens cannot contain the following characters: $<>/\'"` in the site-options.conf file.
      • To disable password obfuscation, set OBFUSCATION_ENABLED=false.
      • To configure the obfuscation key, set OBFUSCATION_KEY=<Any AlphaNumeric value with length >= 8 bytes>. The default value of OBFUSCATION_KEY token is XSJt43wN.
      • To configure the OBFUSCATION_PREFIX, set OBFUSCATION_PREFIX= <A value with 4 to 8 bytes length>. The default value of OBFUSCATION_PREFIX is {OBF}.
    8. Ensure to set the token DEDICATED_INSTALL=true.
    9. Include the list of non-expiring TeamForge user accounts (password never expires).
      Important: If you have 'gitadmin' added to the above list of non-expiring user accounts already, you may skip this step. Otherwise, add a new user, 'scmadmin', to the list of non-expiring user accounts.
    10. Make sure that the following tokens have a value if ETL is enabled.
    11. Configure Black Duck Code Sight tokens. See Black Duck Code Sight site-option tokens.
    12. To enable the history protection feature of TeamForge Git integration, set the GERRIT_FORCE_HISTORY_PROTECTION=true. For more information see GERRIT_FORCE_HISTORY_PROTECTION.
    13. If you have LDAP set up for external authentication, you must set the “REQUIRE_USER_PASSWORD_CHANGE” site options token to false.
    14. If you are installing TeamForge through disconnected media, set the token HELP_AVAILABILITY=local.
    15. Ensure to set the token SELINUX_SETUP=false.
    16. Make sure the PostgreSQL tokens in the site-options.conf file are set as recommended in the following topic:What are the right PostgreSQL settings for my site?
    17. Save the site-options.conf file.
  9. Recreate the runtime environment.
    • cd /opt/collabnet/teamforge-installer/
    • ./ -r -I -V
  10. Reload the svnroot, sf-svnroot, cvsroot, gitroot and var directories.
    • rm -rf /svnroot /cvsroot /sf-svnroot
    • cp -Rpfv /tmp/Prod_backup_dir/svnroot /svnroot
    • cp -Rpfv /tmp/Prod_backup_dir/cvsroot /cvsroot
    • cp -Rpfv /tmp/Prod_backup_dir/sf-svnroot /sf-svnroot
    • cp -Rpfv /tmp/Prod_backup_dir/var /opt/collabnet/teamforge/var
    If Git integration is enabled, do the following:
    • rm -rf /gitroot
    • cp -Rpfv /tmp/Prod_backup_dir/gitroot /gitroot
    • cp -Rpfv /tmp/Prod_backup_dir/gerrit/gerrit/etc /opt/collabnet/gerrit
    • cp -Rpf /tmp/Prod_backup_dir/gerrit/gerrit/.ssh /opt/collabnet/gerrit
    • cp -Rpf /tmp/Prod_backup_dir/gerrit/gerrit/bin /opt/collabnet/gerrit
  11. Recreate the runtime environment to set the database credentials.
    • cd /opt/collabnet/teamforge-installer/
    • ./ -r -I -V
  12. Update the file permissions on your site's data.
    • /opt/collabnet/teamforge/runtime/scripts/
    Note: This process can take a long time for sites with a lot of data.
  13. Run the scripts to change the domain in the file system and database.
    1. Change the domain name in the file system. For more information see
      • cd /opt/collabnet/teamforge/runtime/scripts
      • ./ --dir=/opt/collabnet/teamforge/var/ --old=<old domain name> --new=<new domain name> --debug
    2. Change the domain name in the database. For more information see
      • ./ --old=<old domain name> --new=<new domain name>
  14. Start TeamForge.
    • /etc/init.d/collabnet start
  15. Install the TeamForge license for stage server.
  16. If you have CVS integrations, synchronize permissions post upgrade. See, Synchronize TeamForge source control integrations.
  17. Run the TeamForge post installation script. For more information, see
    • /opt/collabnet/teamforge/runtime/scripts/
  18. Install the Black Duck Code Sight license on the server where Black Duck Code Sight is installed. For more information see these instructions.

Set up Review Board

  1. Create a /var/ops/ folder, download the file from and save it in the /var/ops/ folder.
    Note: Replace 'x' with the appropriate Review Board release number.
  2. Unzip the file.
    • cd /var/ops/
    • unzip
    Note: Replace 'x' with the appropriate Review Board release number.
  3. Update domain name, hostname, site-url in install.conf.
  4. Start the TeamForge application.
    • /etc/init.d/collabnet start all
  5. Before installing Review Board, you must know the password for the scmviewer account. Run the following commands to get the password:
    1. Run the grep command to get the encrypted password.
      • grep SCM_USER_ENCRYPTED_PASSWORD /opt/collabnet/teamforge/runtime/conf/runtime-options.conf
    2. Use the script to decrypt the scmviewer password.
      • /opt/collabnet/teamforge/runtime/scripts/ -decrypt '<value of SCM_USER_ENCRYPTED_PASSWORD>'
  6. Run the following grep commands to get the value of HTTPD_USER, HTTPD_GROUP and HOME_DIR_BASE.
    • grep HTTPD_USER= /opt/collabnet/teamforge/runtime/conf/runtime-options.conf
    • grep HTTPD_GROUP= /opt/collabnet/teamforge/runtime/conf/runtime-options.conf
    • grep HOME_DIR_BASE= /opt/collabnet/teamforge/runtime/conf/runtime-options.conf
  7. Restore the Review Board data if you are upgrading TeamForge and Review Board on a new server.
    Note: Ensure that you have already copied the backup of the Review Board data directory to the /tmp directory of the new server.
    1. Restore the Review Board data directory.
      • cd /opt/collabnet
      • tar -zxvf /tmp/reviewboard_data.tgz
  8. Run the script available in the Review Board installer directory.
    • cd /var/ops/RBInstaller-x.x.x.x.x
    • python ./ -i -r --auth-scmuser
  9. Run the following Review Board domain change script.
    • cd /opt/collabnet/teamforge/runtime/scripts
    • ./ <old domain name> <new domain name>
  10. Restart the TeamForge application.
    • /etc/init.d/collabnet stop all
    • /etc/init.d/collabnet start all

Set up Black Duck Code Sight

  1. Run the following query to get the repository IDs of the repositories for which the Available in Search Results option was enabled.
    echo "select from folder f, project p,scm_repository sr where like 'reps%'and p.is_deleted='f' and project_id and sr.search_enabled='t'and and f.is_deleted='f';" | 
    /opt/collabnet/teamforge/runtime/scripts/psql-wrapper -t -A >>/tmp/repository-ids.txt
  2. As this is a stage server setup, run the script to have the code search project repository URLs point to the stage server.
    Note: Make sure TeamForge and Black Duck Code Sight licenses are installed before running the script.
    • /opt/collabnet/teamforge/runtime/scripts/codesearch/ --filename=/tmp/repository-ids.txt
  3. Run the script.
    • cd /opt/collabnet/teamforge/runtime/scripts/codesearch/
    • ./ <Repository Base URL Path>