Preparing your Unix/Linux server for installation - 8.0.1.1029 version

Preparing the server

TestRail requires a web server, a SQL based database (MySQL), a NoSQL database (Cassandra 3.11), and a working PHP environment to be installed on the server. While instructions for installing Linux, Apache, MySQL, and PHP (commonly referred to as LAMP) are out of the scope of this installation guide, 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 Red Hat/CentOS
• Apache, MySQL and PHP on FreeBSD

Installing LAMP on Ubuntu:

To install on Ubuntu, follow these steps:

1. Install MySQL

   apt-get -y install mysql-server mysql-client

   Secure the mysql installation. It is advisable, when prompted, to allow removal of anonymous users and remove the test database. Make sure to allow the program to reload the privilege tables.

   mysql_secure_installation

   MySQL will create the root user by default. Access MySQL console with the following command to create new users.

   sudo mysql --defaults-file=/etc/mysql/debian.cnf

2. Install Apache Web Server

   apt-get -y install apache2

   To ensure the Apache server is running, navigate to ‘http://localhost’ in your web browser. If the Apache Web Server was installed successfully, you will see the Apache2 Ubuntu Default Page.

   
3. Install PHP 8.1

   apt-get -y install php8.1 libapache2-mod-php8.1

4. Restart Apache

   systemctl restart apache2

5. Create the phpinfo.php file

   Follow the Running phphinfo() diagnostics guide to create the phpinfo.php file.

    

   You may need to change the owner of the phpinfo.php file. Use the following command, or a modification of the command to point to the specific location of your phpinfo.php file.

   chown www-data:www-data /var/www/html/phpinfo.php

   If you already have a phpinfo.php file in the wwwroot folder, skip the creation of the file and navigate to ‘localhost/phpinfo.php’ in your web browser to check the PHP version info. It should look something like this (take note that the proper version is reflected in the title):

   

    

   Please review the phpinfo page that lists all the required php extensions including Cassandra.

6. Install the MySQL PHP 8.1 extension

   sudo apt-get install php8.1-phpdbg -y

7. Restart Apache

   systemctl restart apache2

Important notes before installation

Installing the prerequisites

To use TestRail on a Unix-based server with MySQL & Cassandra databases, the following PHP extensions are required:

• gd PHP extension for generating charts
• mysql PHP extension to access the database
• fileinfo PHP extension for determining file type and encoding
• imagick PHP extension for working with images
• mbstring PHP extension for working with Unicode strings
• curl PHP extension to check for updates etc.
• openssl PHP extension to handle SSL connections

Most extensions are installed by default, but mbstring, gd, and imagick need to be installed manually. You can do this using the following command:

$ apt-get -y install php8.1-imagick php8.1-mbstring php8.1-gd

You also need to install the Cassandra driver for your TestRail installation operating system.

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 php8.1-mysql php8.1-curl php8.1-json php8.1-mbstring php8.1-xml php8.1-gd php8.1-zip -y

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 ‘extension={extension_name}’ to the end of the configuration file (make sure that they aren’t already activated in the PHP.ini).

For example, with the filename ‘imagick.so’, the entry in the php.ini file will look like this:

extension=imagick

On most systems you can find the PHP.ini under /etc/php/8.1, /etc/php or /etc/php/8.1/apache2. You will also need to modify the PHP.ini file in the /etc/php/8.1/cli/ directory.

Most PHP 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 php8.1-json module).

Ioncube installation

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_8.1.so

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 8.1.2-1ubuntu2.10 (cli) (built: Jan 16 2023 15:19:49) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.2, Copyright (c) Zend Technologies
    with the ionCube PHP Loader v12.0.5, Copyright (c) 2002-2022, by ionCube Ltd.
    with Zend OPcache v8.1.2-1ubuntu2.10, Copyright (c), by Zend Technologies