TestRail Installation on Unix

Installation

on Unix/Linux

Please see below for

instructions on how to install TestRail on common Unix-based server

systems, including Linux. See therequirementsto

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

asLAMP)

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

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, themysqlandcurlPHP

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/phpor/etc/php5/apache2:

extension=mysql.so

extension=curl.so

Thejsonandmbstringextensions

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

aphp5-jsonmodule).

The last required PHP

extension is the free ionCube PHP loader. You can download the

relevant ionCube edition for your operating system fromionCube'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

thezend_extensionorzend_extension_tsconfiguration

directives and specify thefull

pathto

the extension:

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

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

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

If you are unsure

which ionCube extension you need to activate for your server system,

please copy theloader-wizard.phpscript

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

runningphp

-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 ifphp

-voutputs

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.

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 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 setutf8with

theutf8_unicode_cicollation

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'swwwdirectory

(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 newtestraildirectory

on your web server to launch the TestRail Installation Wizard

(e.g.http:///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 yourwwwdirectory

(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 acronjob.

If you are using an OS X based server system, you might

want to consider using alaunchd

scriptinstead.

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/testrailwith

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 thephp

-vcommand.

If it's not already installed, install thephp5-clipackage

or equivalent with your platform's package manager.

Please note:Also

make sure to add the above mentioned PHP extensions to thephp-cli's

PHP.ini if it doesn't use the web server's PHP.ini file. E.g., on

Ubuntu systems, also add theioncubeextension

to/etc/php5/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.:

http:///testrail/