Installation - Installation on Unix/Linux - TestRail

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.

Preparing the server

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

TestRail has been designed to have as few dependencies on external applications and PHP extensions as possible to make it run on various operating systems and platforms. To use TestRail on a Unix-based server with a MySQL database, 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).
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

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:

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:


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):


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.

Creating the empty TestRail database

TestRail’s installer automatically creates all needed database tables and initial data in the next step, but you first need to create an empty database and database user. To do this, use your favorite MySQL administration tool (such as phpMyAdmin), or use the mysql command line tool to create the database table and user:

$ mysql -u root -p 
> CREATE USER 'testrail'@'localhost' IDENTIFIED BY 'newpassword';
> GRANT ALL ON testrail.* TO 'testrail'@'localhost';

If you are creating the database and user manually, please make sure to specify the default character set utf8 with the utf8_unicode_ci collation and grant the new user all privileges to the TestRail database.

Installing TestRail

To install the actual application, just upload and extract the TestRail installation archive to your web server and copy the files to your web server’s www directory (e.g., on Ubuntu it’s /var/www/html/testrail). Some Unix systems do not support the unzip command by default, so you might have to install it first (example shows Ubuntu/Debian):

$ sudo apt-get install unzip

Then just point your web browser to the new testrail directory on your web server to launch the TestRail Installation Wizard (e.g. http://<server>/testrail/) and follow the instructions:

The installer will ask you to specify directories to store attachments, reports and log files. Please create those directories and make sure that the directories are writable by the web server. With the attachment and report directories, also make sure that they aren’t directly accessible with a web browser for security reasons, so specify a directory outside your www directory (for example, /opt/testrail/attachments). To make the directories writable by your web server, just change the ownership of the directories to your web server user. For example, on Ubuntu systems:

$ sudo chown www-data:www-data /var/www/html/testrail/logs/
$ sudo chown www-data:www-data /opt/testrail/attachments/
$ sudo chown www-data:www-data /opt/testrail/reports/

Activating the TestRail background task

The last step of the TestRail installation consists of installing the background task. The background task is responsible, among other things, for sending out email notifications for test changes if this feature is enabled. The background task needs to be triggered in regular intervals to do its work and the easiest way to do this under Unix-based systems is to add a cron job. If you are using an OS X based server system, you might want to consider using a launchd script instead.

Before scheduling the task, you can verify that the background task can be successfully started by running it manually from the command line:

$ php /var/www/html/testrail/task.php

The TestRail background task automatically detects if it’s already running, so it’s best to trigger the task in very short intervals (such as every minute) for best results. To do this, make sure cron is installed on your system and create a file /etc/cron.d/testrail with the following content:

* * * * * www-data /usr/bin/php /var/www/html/testrail/task.php

The cron job needs the PHP command line interface, which might already be installed on your system. You can test this by executing the php -v command. If it’s not already installed, install the php7.3-cli package or equivalent with your platform’s package manager.

Please note: Also make sure to add the above mentioned PHP extensions to the php-cli’s PHP.ini if it doesn’t use the web server’s PHP.ini file. E.g., on Ubuntu systems, also add the ioncube extension to /etc/php/7.3/cli/php.ini.

That’s it! If everything worked, your TestRail installation is complete and you can start using the application by accessing it with your web browser, i.e.: