Upgrading TestRail From 7.5.3 to 8.x in Unix/Linux


TestRail 8.0 is available for all Server customers. Customers who wish to upgrade to TestRail 8 should request the installation files here: TestRail 8 Installation Files Request Form

Below, you will find information on how to upgrade an existing TestRail installation to a new version. Please follow these steps to upgrade your TestRail installation.

As of TestRail 8, PHP 7.4 is no longer supported. You can learn how to upgrade PHP here.


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.


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.


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


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)


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. 


If you do not have a phpinfo.php file follow the Running Phpinfo diagnostics process to create it.

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:



Download and install the ‘php_cassandra.so’ file.


'php_cassandra.so' is the exact file required for TestRail 8.0 running in Unix/Linux.

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)



Do not include the ‘php_’ prefix or the ‘.so’ extension in the INI file contents.

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"

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.


Some web server configurations can prevent files from being overridden while the web server is active. You might need to stop the web server before replacing TestRail’s installation files. This can happen mainly with Windows/IIS systems. If you have upgrade issues, try stopping the web server and overriding the files again.

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.


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:

| 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);
Was this article helpful?
0 out of 1 found this helpful