Installation - Installation on Windows - TestRail

Installation on Windows

Please see below for instructions on how to install TestRail on a Windows Server system. Click here to learn more about the supported operating and server systems.

On this page:

    Please note: 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 for best performance and reliability, as explained below. The alternative 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 or MySQL), a NoSQL database (Cassandra 3.11), and a working PHP 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. The easiest way to install PHP on Windows is to use Microsoft’s Web Platform Installer.

    To install PHP with the Web Platform Installer, select the Products tab at the top of the window and select the following packages (by pressing the Add buttons next to the packages):

    • PHP 7.3.x or PHP 7.4.x
    • Microsoft Drivers 5.8 for PHP 7.3 for SQL Server in IIS or Microsoft Drivers 5.8 for PHP 7.4 for SQL Server in IIS

    The SQL Driver package is required by TestRail to connect to SQL Server databases. Next, install both packages and all dependencies (such as IIS itself) by clicking the Install button. Please make sure to install the full IIS Edition and not IIS Express.

    If you don’t want to use the Web Platform Installer to install PHP, Microsoft also explains how to install PHP manually on IIS 6 and IIS 7. You should also install the Microsoft SQL Server Driver for PHP when installing PHP manually. The driver needs the SQL Server Native Client to be installed (this is installed automatically for you when you use the Web Platform Installer).​

    Installing the prerequisites

    To use TestRail on Windows with a SQL Server database, the following PHP extensions are required:

    • sqlsrv PHP extension to access SQL Server databases
    • curl PHP extension to check for updates etc.
    • json PHP extension for config files and integrations
    • mbstring PHP extension for working with Unicode strings
    • ioncube PHP loader to decode the TestRail PHP files
    • zlib PHP extension that enables you to transparently read and write gzip (.gz) compressed files (required for enterprise customers only).
    • PDO_Dblib extension for Phinx to run properly

    You’ll also need to install the Cassandra driver for your TestRail installation operating system (see here).

    Please Note: Refer to the Cassandra installation instructions for more details about Cassandra prerequisites and full installation/configuration.

    If you installed PHP with the Web Platform Installer as described above, most extensions should be added automatically, but you will need to run through the additional Cassandra and IonCube steps. If you installed PHP manually, you might have to activate the required extensions in the PHP.ini file like this:

    extension=php_sqlsrv.dll
    extension=php_curl.dll
    extension=php_json.dll
    extension=php_mbstring.dll
    extension=php_pdo_sqlsrv.dll

    The last required PHP extension is the free ionCube PHP loader. You can download the ionCube loader for Windows here. See the below chart as a reference for which version to download.

     

    PHP Version Ioncube Loader
    7.3 & 7.4

     

    Windows VC15 (Non-TS) (32 bits)
    Windows VC15 (Non-TS) (64 bits)

     

    After downloading and extracting the files on your server, copy the loader extension for your PHP version (e.g. ioncube_loader_win_7.3.dll) to your PHP’s ext directory (usually C:\\Program Files (x86)\\PHPv7.3\\ext or similar). Next, activate the extension by adding the following line to your PHP.ini file (please adjust the directory accordingly and use two backslashes as the directory separator). You must specify the full path to the file. You can find the PHP.ini file in your PHP installation directory (usually C:Program Files (x86)PHP7.3 or similar):

    zend_extension = 
    "C:\\\\Program Files\\\\PHP\\\\v7.3\\\\ext\\\\ioncube_loader_win_7.3.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 7.3.25 (cli) (built: Nov 24 2020 13:41:31) ( NTS MSVC15 (Visual C++ 2017) x64 )
    Copyright (c) 1997-2018 The PHP Group
    Zend Engine v3.3.25, Copyright (c) 1998-2018 Zend Technologies
    with the ionCube PHP Loader v10.4.5, Copyright (c) 2002-2020, by ionCube Ltd.

    info Please Note: 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.

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