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:
LAMP on Debian
LAMP on Ubuntu
LAMP on Red Hat/CentOS
MySQL and PHP on Mac OSX
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/
