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
As TestRail is a web application (based on PHP), TestRail requires a web server, a database (MySQL) and a working PHP environment to be installed on the server. Installing Linux, Apache, MySQL and PHP (commonly referred to as LAMP) is out of scope of this installation guide. However, there are great how-to guides on how to install a LAMP system on popular Linux and Unix systems available on the net:
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:
mysqlPHP extension to access the database
curlPHP extension to check for updates etc.
jsonPHP extension for config files and integrations
mbstringPHP extension for working with Unicode strings
ioncubePHP loader to decode the TestRail PHP files
Depending on the operating system and platform, the
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 php5-mysql php5-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
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
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
To activate ionCube, add the relevant ionCube loader extension to your PHP.ini. To do this, make sure to use the
zend_extension_ts configuration directives and specify the full path to the extension:
If you are using a different PHP version (e.g. PHP 5.3 or PHP 5.5), please make sure to specify the corresponding version of the ionCube loader. For example, for PHP 5.3 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 5.2.10 (cli) (built: Jun 17 2009 16:06:30) Copyright (c) 1997-2007 The PHP Group Zend Engine v2.2.0, Copyright (c) 1998-2007 Zend Technologies with the ionCube PHP Loader v3.1.34, Copyright (c) 2002-2009, by ionCube Ltd.
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 DATABASE testrail DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci; > 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.
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/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/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/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/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
php5-cli package or equivalent with your platform's package manager.
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
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.: