Preparing your Windows server for the installation - versions 9.4.1 to 9.8.1

TestRail requires a web server, a SQL database (SQL Server) 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.

Download the official PHP files in .zip format. Use the latest 8.1 version available. 

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:

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

• Download the x86 package
• Download the x64 package

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.

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.

Most extensions should be added automatically, 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=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).

Install Chrome Headless Shell Dependency (for Reports)

1. Install Dependencies - Please ensure that your system has the ability to unarchive ZIP files.
2. Download Chrome Headless Shell Manually - Open the Chrome for Testing website in a browser and download the latest stable version
3. Unzip the File - Right-click the .zip and select "Extract All"
4. Move to Desired Location - Move the extracted folder anywhere (e.g., C:\Program Files\ChromeHeadless). Keep note of the location where you will move the binary, as you will need to add this path to the TestRail configuration.