TestRail 8.0.4 is available for all Server customers. Customers who wish to upgrade to TestRail 8.0.4 can download the installation files from the Customer Portal.
The instructions below will help you understand how to install TestRail on a Windows Server system. You can learn more about the supported operating and server systems here.
We recommend not using Windows PHP/Apache/MySQL all-in-one packages (such as XAMPP). Instead, we recommend using IIS, PHP with FastCGI, and SQL Server for Windows environments to ensure the best performance and reliability, as explained below. The alternative option would be to use Linux, Apache, and MySQL, but both environments work equally well.
Preparing the server
TestRail requires a web server, a SQL database (SQL Server), a NoSQL database (Cassandra 3.11), and a working PHP 8.0 or 8.1 environment to be installed on the server. On Windows Servers, TestRail works best with Microsoft’s IIS web server and PHP configured to run with FastCGI.
Installing IIS
To install IIS on Windows Server, run Server Manager. On the Dashboard, under Configure This Local Server, click Add roles and features.
Select Role-based or feature-based installation, and click Next.
Select your desired server host to install IIS from the server pool, and click Next. Then, when selecting Server Roles, make sure Web Server (IIS) is selected and under Web Server > Application Development make sure CGI is also selected (if it is not selected already). Click Install.
For more information, please refer to Microsoft’s official documentation:
Download the official PHP files in .zip format.
As of 2023, VS16 x64 Non Thread Safe is the recommended version to download, as this will be used in the installation documentation.
Once the download is complete, extract the zipped PHP files into C:\php\ on the host system.
Edit your Environment Variables, and add a new Path System variable C:\php.
Go to the IIS Manager, click on the server host, then click Handler Mappings, and Add Module Mapping.
On the new window, fill in all the fields with the exact information shown on the following image, and then click OK.
Go back to the server host in the IIS Manager, and this time click Default Document. Click Add on the Actions Panel.
Fill in the Name field with Index.php and click OK. Next, click Add again and this time fill in the Name field with Default.php and click OK.
Installing the prerequisites
To use TestRail on Windows with a SQL Server database, the following PHP extensions are required:
- cassandra extension to access the NoSQL database
- gd PHP extension for generating charts
- sqlsrv_81_nts_x64 PHP extension to access SQL Server databases
- pdo_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
- ioncube PHP loader to decode the TestRail PHP files
Download the PHP Microsoft drivers for SQL Server here, and click Download Microsoft Drivers for PHP for SQL Server (Windows).
Before extracting the files, you must first make sure which Thread Safety you have for your PHP version (ts or nts), otherwise the installation will not work. To see if your version is enabled for Thread Safe or Not Thread Safe, enter the following command:
php -i|find "Thread Safety"
Once you have extracted the files, find the corresponding Thread Safety files according to your version and copy the files to your C:\php\ext\ directory. For example:
-
- php_pdo_sqlsrv_81_nts_x64.dll
- php_sqlsrv_81_nts_x64.dll
To install these extensions, add the following to your php.ini files:
-
- extension=pdo_sqlsrv_81_nts_x64
- extension=sqlsrv_81_nts_x64
The driver also needs the ODBC Driver to be installed. Download the corresponding package and install it:
After you activate the extension in the PHP.ini configuration file and after you installed the ODBC Driver, please restart your IIS web server. You can check if the extension has been successfully loaded by running the phpinfo() function. You can use the Command Prompt to run ‘php -m’ to confirm the modules are running.
Follow the official imagick extension installation documentation found here.
Refer to the Cassandra installation instructions for more details about Cassandra prerequisites and full installation/configuration.
The last required PHP extension is the free ionCube PHP loader. You can download the ionCube loader for Windows here.
This installation procedure requires ‘ioncube_loader_win_8.1.dll’, which is found by downloading the Windows VC16 (Non-TS) (64 bits) zip file (ioncube_loaders_win_nonts_vc16_x86-64.zip). Extract all the files on your server, and copy the loader extension to your PHP’s ext directory (usually C:\php\ext\). Next, activate the extension by adding the following line to your PHP.ini file (You can find this file in your installation directory, usually C:\php\):
zend_extension = "C:\php\ext\ioncube_loader_win_8.1.dll"
To verify that the ionCube loader extension has been successfully installed, run php -v in the Windows Command Prompt (you need to change to PHP’s installation directory in order to execute this command).
The ionCube loader extension is successfully installed if php -v outputs something like this (note the ionCube PHP Loader line):
PHP 8.1.14 (cli) (built: Jan 4 2023 12:24:57) (NTS Visual C++ 2019 x64)
Copyright (c) The PHP Group
Zend Engine v4.1.14, Copyright (c) Zend Technologies
with the ionCube PHP Loader v12.0.5, Copyright (c) 2002-2022, by ionCube Ltd.
In order for IIS to be able to load the extension, you might need to change the permission of the ionCube extension file. To do this, right-click the file in Explorer, click Properties, select the Security tab, and add the Users group.
Most extensions should be added automatically, but you will need to run through the additional Cassandra, IonCube, and imagick steps. If you installed PHP manually, you might have to activate the required extensions in the PHP.ini file like this:
zend_extension = "C:\php\ext\ioncube_loader_win_8.1.dll"
extension=cassandra
extension=gd
extension=fileinfo
extension=imagick
extension=mbstring
extension=curl
extension=openssl
extension=pdo_sqlsrv_81_nts_x64
extension=sqlsrv_81_nts_x64
To reload PHP, restart the IIS web server. The easiest way to do this is to restart the World Wide Web Publishing Windows service. You can do this by opening the Services application from the Administrative Tools and restarting the service. (Please note that this restarts all IIS application pools and websites. If you are hosting other websites and applications on this server, you might want to restart the relevant application pool only).