Preparing your Unix/Linux server for installation

Installation on Unix/Linux

Please see below for instructions on how to install TestRail on common Unix-based server systems, including Linux. See the requirements to learn more about supported operating and server systems.

On this page:

• Preparing the server
• Important notes before installation
• Installing the prerequisites

Preparing the server

TestRail requires a web server, a SQL based database (MySQL), a NoSQL database (Cassandra 3.11), and a working PHP environment to be installed on the server. While instructions for installing Linux, Apache, MySQL and PHP (commonly referred to as LAMP) is out of scope of this installation guide, there are great how-to guides on how to install a LAMP system on popular Linux and Unix systems available on the net:

• Installing LAMP on Debian
• Installing LAMP on Ubuntu
• Installing LAMP on Red Hat/CentOS
• Apache, MySQL and PHP on FreeBSD

Important notes before installation

Please Note: From TestRail 7.1 onwards, TestRail requires both MySQL (or MariaDB) and Cassandra databases, plus related drivers.

Installing the prerequisites

To use TestRail on a Unix-based server with MySQL & Cassandra databases, the following PHP extensions are required:

• mysql PHP extension to access the database
• curl PHP extension to check for updates etc.
• json PHP extension for config files and integrations
• mbstring PHP extension for working with Unicode strings
• ioncube PHP loader to decode the TestRail PHP files
• xml PHP extension for xml import/export
• zip PHP extension for zipping email attachments
• zlib PHP extension that enables you to transparently read and write gzip (.gz) compressed files (required for enterprise customers only).
• gd php extension for generating charts

You also need to install the Cassandra driver for your TestRail installation operating system (see here).

Please Note: Refer to Cassandra installation instructions for more details about Cassandra prerequisites and full installation/configuration.

Note: TestRail 5.5 included PhantomJS for the production of PDF reports, for which some administrators have reported additional libfontconfig1 & fontconfig dependencies. See thread here for more info.

Depending on the operating system and platform, the mysql and curl PHP extensions must be installed (via the platform’s package manager) and activated in the PHP.ini configuration file. For example, the following command installs the extensions on Debian/Ubuntu systems:

$ sudo apt-get install php7.3-mysql php7.3-curl php7.3-json 
php7.3-mbstring php7.3-xml php7.3-gd php7.3-zip -y

On some systems, these modules also have to be activated in the PHP.ini configuration file (systems such as Ubuntu automatically activate the extensions when they are installed). To do this, please add the following lines to the end of the configuration file (make sure that they aren’t already activated in the PHP.ini). On most systems you can find the PHP.ini under /etc/php7.3, /etc/php or /etc/php7.3/apache2:

extension=mysql.so
extension=curl.so

The json and mbstring extensions are usually integrated directly into PHP and don’t require an external module to be installed. However, if you see a missing dependency message in TestRail for one of these modules, you need to add it to your PHP installation as well (e.g. by installing a php7.3-json module).

The last required PHP extension is the free ionCube PHP loader. You can download the relevant ionCube edition for your operating system from ionCube’s website. After downloading and extracting the files on your web server, place the files in a directory of your choice, for example /opt/ioncube.

To activate ionCube, add the relevant ionCube loader extension to your PHP.ini. To do this, make sure to use the zend_extension or zend_extension_ts configuration directives and specify the full path to the extension:

zend_extension=/opt/ioncube/ioncube_loader_lin_7.3.so

If you are using a different PHP version (e.g. PHP 7.4), please make sure to specify the corresponding version of the ionCube loader. For example, for PHP 7.4 you would need to load the ionCube loader as follows instead (note the different version in the file name):

zend_extension=/opt/ioncube/ioncube_loader_lin_7.4.so

If you are unsure which ionCube extension you need to activate for your server system, please copy the loader-wizard.php script to your web server directory and access it from your web browser and follow the installation instructions. After installing the extensions, please restart your web server to load the newly installed extensions.

You can verify that the ionCube loader extension has been successfully installed by running php -v. Please note though that the PHP command line interface might use a different configuration file than the PHP version that is used by your web server. Please make sure that ionCube is activated in all relevant PHP.ini configuration files. The ionCube loader extension is successfully installed if php -v outputs something like this (note the ionCube PHP Loader line):

PHP 7.3.25 (cli) (built: Nov 24 2020 xx:xx) 
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.3.25, Copyright (c) 1998-2018 Zend Technologies
    with the ionCube PHP Loader v10.4.5, Copyright (c) 2002-2020, by ionCube Ltd.

SELinux note: If your system has SELinux enabled (often on RedHat and similar Linux distributions), Apache and/or PHP might not be able to load ionCube or other files due to directory restrictions. If you experience this problem, you can either adjust the SELinux configuration or disable SELinux, depending on your requirements.