1.3 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.

1. 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 LAMP on Debian
• Installing LAMP on Ubuntu
• Installing LAMP on Red Hat/CentOS
• Apache, MySQL and PHP on Mac OSX
• Apache, MySQL and PHP on FreeBSD

2. 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.
• ioncube PHP loader to decrypt the TestRail PHP files

Depending on the operating system and platform, both 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 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 /etc/php5, /etc/php or /etc/php5/apache2:

extension=mysql.so
extension=curl.so

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_5.2.so

If you are unsure which ionCube extension you need to activate for your server system, please copy the ioncube-loader-helper.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.

3. Creating the empty TestRail database

TestRail's installer will automatically create 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 latin1 COLLATE latin1_general_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 latin1 with the latin1_general_ci collation and grant the new user all privileges to the TestRail database.

4. 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/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 and log files in. Please make sure that these directories are writable by the web server. With the attachment directory, also make sure that it's not 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/

5. 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.

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.

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

http://<server>/testrail/

Back to TestRail Administration Guide