Upgrading TestRail From 7.5.3 to 8.0.1 in Unix/Linux

Backup

It is strongly recommended to make a backup of your TestRail installation files and TestRail database before upgrading to a newer version. In case there’s a problem with the upgrade, a backup is the only way to roll back the changes and revert to your previous (working) installation. We recommend making backups of your TestRail installation and database regularly, especially before upgrading to a newer version.

Requirements

Before proceeding with an upgrade to TestRail, please review the requirements documentation and operating specific instructions (Windows/Linux). Software dependencies such as PHP and SQL can change over time, so it is important to review these requirements prior to updating your TestRail software.

Upgrading the dependencies

PHP 8.1

TestRail 8.0 requires PHP 8.1.  The first step in this upgrade is to install PHP8.1.

Run

sudo apt install php8.1

Choose the version of PHP you wish to use (8.1 in this case).

sudo update-alternatives --config php

Restart Apache

systemctl restart apache2

ionCube

The last required PHP extension is the free ionCube PHP loader. You can navigate to the ionCube directory (this document assumes /opt/ioncube/), download, and install the ionCube loader for Unix/Linux by running the following commands:

Change Directory to /opt/ioncube

cd /opt/ioncube

Download ioncube files

wget https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.zip

Extract ioncube files

unzip ioncube_loaders_lin_x86-64.zip

Update php.ini (/apache and /cli) file with new ioncube loader (Usually ‘/etc/php/8.1/cli/php.ini’ & /etc/php/8.1/apache2/php.ini)

zend_extension=/opt/ioncube/ioncube_loader_lin_8.1.so

If you still have a phpinfo.php file in the wwwroot folder, skip the following step to create the phpinfo.php file and navigate to ‘localhost/phpinfo.php’ in your web browser. 

Navigate to localhost/phpinfo.php in your web browser to check the PHP version info.  It should look something like this (take note that the proper version is reflected in the title):

Please review the phpinfo page that lists all the required php extensions including Cassandra.

To verify that the ionCube loader extension has been successfully installed, run ‘php -v’

php -v

The ionCube loader extension is successfully installed if ‘php -v’ outputs something like this (note the ionCube PHP Loader line):

PHP 8.1.15 (cli) (built: Feb  7 2023 11:31:13) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.15, Copyright (c) Zend Technologies
with the ionCube PHP Loader v12.0.5, Copyright (c) 2002-2022, by ionCube Ltd.
with Zend OPcache v8.1.15, Copyright (c), by Zend Technologies

PHP Extensions

To use TestRail on Linux with a MySQL Server database, the following PHP extensions are required:

• • cassandra extension to access the NoSQL database
  • gd PHP extension for generating charts
  • mySQL extension to access the database
  • pdo_mysql PHP extension to access the database
  • fileinfo PHP extension for determining file type and encoding
  • imagick PHP extension for working with images
  • mbstring PHP extension for working with Unicode strings
  • curl PHP extension to check for updates etc.
  • openssl PHP extension to handle SSL connections

Usually, the php extension directory can be found in ‘/usr/lib/php/20210902/’.  This document assumes that this is our extension directory.

Most extensions are there by default, but you will need to manually install mbstring, gd, and imagick.  

gd, fileinfo, mbstring, curl, openssl, & imagick

These can be installed using the following command:

apt-get -y install php8.1-imagick php8.1-mbstring php8.1-gd

Add the extensions to your php.ini file:

extension=gd
extension=fileinfo
extension=mbstring
extension=curl
extension=openssl
extension=imagick

Cassandra

Download and install the ‘php_cassandra.so’ file.

Download this Cassandra driver file here.

Copy the files to your PHP’s extension directory (usually: /usr/lib/php/20210902/).

cp -r /tmp/cassandra.so /usr/lib/php/20210902/

Update php.ini (/apache and /cli) file with new ioncube loader (Usually ‘/etc/php/8.1/cli/php.ini’ & /etc/php/8.1/apache2/php.ini)

extension=cassandra

To reload PHP, restart the apache web server. 

systemctl restart apache2

Wrapping Up

When all installations are completed, run the following command to enable the PHP 8.1 version for Apache:

a2enmod php8.1

After updating PHP, ionCube Loader, gd, mbstring, imagick, & Cassandra, your php.ini file should turn out looking very similar to the following example:

zend_extension ="/opt/ioncube/ioncube_loader_lin_8.1.so"
extension=cassandra
extension=gd
extension=fileinfo
extension=imagick
extension=mbstring
extension=curl
extension=openssl
extension=mysql

Replace installation files

To upgrade your TestRail installation, upload and extract the TestRail installation files to your web server and copy the files of the new TestRail version over your existing installation files. You can just replace all files, as files that are unique to your installation (e.g. the config.php file) aren’t part of the installation archive.

Once the files have been replaced, the instance has been upgraded.  Log into the instance via web browser (usually ‘http://localhost/testrail/’ or something similar) to confirm a successful upgrade.

MAX_CHART_ROWS

If users upgrade to 8.0 without adding MAX_CHART_ROWS to the config.php file, an error appears like the one shown below:

To fix this, add the constant:

/*
|--------------------------------------------------------------------
| OPTIMIZATIONS
|--------------------------------------------------------------------
|
| You can choose whether to optimize the delivery of style sheet and
| javascript files and the handling of language files. The following
| optimization settings are available:
|
| DEPLOY_OPTIMIZE_LANG:   If enabled, TestRail uses a single combined
|                         language file named 'all_lang' instead of
|                         multiple language files.
|
| DEPLOY_OPTIMIZE_CSS:    If enabled, a single combined style sheet
|                         is served to the clients.
|
| DEPLOY_OPTIMIZE_JS:     If enabled, a single combined javascript
|                         file is served to the clients.
*/


define('DEPLOY_OPTIMIZE_LANG', true);
define('DEPLOY_OPTIMIZE_CSS', true);
define('DEPLOY_OPTIMIZE_JS', true);


define('MAX_CHART_ROWS', 150000);