Installation on Windows
Please see below for instructions on how to install TestRail on a Windows Server system. See the requirements to learn more about the supported operating and server systems.
Preparing the server
As TestRail is a web application (based on PHP), TestRail requires a web server, a database (SQL Server or MySQL) 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. Now 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. 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
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 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
If you installed PHP with the Web Platform Installer as described above, all extensions but the ioncube loader are already installed and activated. 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.3ext or similar). Now activate the extension by adding the following line to your PHP.ini file (please adjust the directory accordingly and use two backslashes as 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"
You can verify that the ionCube loader extension has been successfully installed by running php -v in the Windows Command Prompt (you need to change to PHP’s installation directory in order the 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, it might be needed to change the permission of the ionCube extension file. To do this, right-click the file in Explorer, Properties, select the Security tab and add the Users group.
To reload PHP, you now need to 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).
Creating the empty TestRail database
TestRail’s installer will automatically create all needed database tables and initial data in the next step, but you first need to create an empty database and database user. You can use a SQL Server database when you install TestRail on Windows.
You can either install the free Microsoft SQL Server 2017 Express edition or use a full SQL Server installation. If you download the Express edition, make sure to download and install the version with Advanced Services, as it is very likely that TestRail will make use of the database’s full-text search feature in the future. Also make sure to use Mixed Mode Authentication, as this is required by TestRail. After installing the database and management tool (Management Studio), continue with creating an empty database and user.
To create the empty TestRail database, start the SQL Server Management Studio, then right click Databases in the left tree and select New Database.
Now create a new TestRail login by expanding Security in the left tree, right-clicking Logins and selecting New Login. You need to specify SQL Server authentication as the authentication method, specify a password, and deselect all three password checkboxes below:
SQL Server distinguishes between server logins and database users, so in order to access the TestRail database with the newly created login, we also need to add a user to the database. To do this, expand the TestRail database in the left tree, expand Security, right-click Users and select New User. Specify the user name and login name and make sure to assign the db_owner role to the user.
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’s wwwroot directory (e.g., C:inetpubwwwroot). Alternatively you can set up a virtual directory in IIS and install the TestRail files in another location.
Then just point your web browser to the new TestRail directory on your webserver to launch the TestRail Installation Wizard (e.g. http://<server>/testrail/) and follow the instructions.
Permission problem (401)? If you get a 401 permission error when you try to access the TestRail installer, you need to make sure that IIS can read and execute the PHP files. To do this, right-click the testrail directory in Explorer, right-click, Properties and then select the Security tab. If the IIS user isn’t listed, click Add, enter the IIS user (IUSR under Windows 2008 and later, IUSR_<hostname> under Windows 2003) and confirm with OK. Then check the Read & Execute, List Folder Contents and Read permissions. Also important: click the Advanced button and check the “Replace permission entries on all child objects with entries shown here that apply to child objects”. Now close all dialogs by clicking OK.
SQL Server Express / named instance? If you installed SQL Server Express (or another SQL Server edition) as a named-instance, you might need to enter the instance name as part of the server name when connecting TestRail to your database. That is, on the second installation wizard page, you would need to enter both the hostname as well as for instance name into the Server field. For example, for a local SQL Server Express instance, with an instance name of sqlexpress:
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 webserver. 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 your wwwroot directory (for example, C:TestRailAttachments). To make the directories writable by IIS, add the IUSR user to the security settings of the directories and grant full permissions to this user (on Windows Server 2003 systems, the user is usually called IUSR_<hostname>):
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 Windows is to create a scheduled task.
Before scheduling the task, you can verify that the background task can be successfully started by running it manually from the command line (x86 and x64):
> "C:Program FilesPHPv7.3php.exe" "C:inetpubwwwroottestrailtask.php" > REM Or, for x64 systems: > "C:Program Files (x86)PHPv7.3php.exe" "C:inetpubwwwroottestrailtask.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.
You can create the task using the command line. For example, on Windows Server 2008:
> schtasks /create /np /sc minute /mo 1 /tn "TestRail Background Task" /tr ""C:Program FilesPHPv7.3php.exe" C:inetpubwwwroottestrailtask.php" > REM Or, for x64 systems: > schtasks /create /np /sc minute /mo 1 /tn "TestRail Background Task" /tr ""C:Program Files (x86)PHPv7.3php.exe" C:inetpubwwwroottestrailtask.php"
Alternatively, you can also use the Task Scheduler GUI. To do this, open the Windows Task Scheduler and select Create Basic Task (Windows 2008). Now specify a task name and select to trigger the task even if no user is logged on:
On the Triggers tab, add a new trigger to specify when the task should be executed:
And last but not least, add the action to execute the TestRail task script on the Actions tab. As the script is a PHP script, we need to specify the path of the php.exe and the task.php script as an argument (including quotes):
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.: