Skip to content
Official repo for TestRail docker support.
Shell Dockerfile PHP
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
Dockerfiles Refactoring and fine tuning Jul 1, 2019
_config Heavy refactoring Jun 14, 2019
_mysql Added missing file Jul 1, 2019
_opt Adjusted volumes Jun 14, 2019
.gitignore Official TestRail dockerhub repo now in use + cleanup script and some Jul 5, 2019
LICENSE Initial commit Sep 14, 2018 Extended readme Jul 17, 2019 Official TestRail dockerhub repo now in use + cleanup script and some Jul 5, 2019 Official TestRail dockerhub repo now in use + cleanup script and some Jul 5, 2019
docker-compose.yml Extended readme Jul 17, 2019
docker-compose_documented.yml Official TestRail dockerhub repo now in use + cleanup script and some Jul 5, 2019
docker-compose_external_db.yml Extended readme Jul 17, 2019
docker-compose_nginx.yml Added support for beta Jul 5, 2019 Official TestRail dockerhub repo now in use + cleanup script and some Jul 5, 2019

TestRail - let's put it in docker containers

What's in this repository?

This repo contains Dockerfiles and compose files to spawn TestRail in docker containers. The compose files rely on public available TestRail images available here.


  • Install docker + docker-compose (on Linux, using pip is recommended)
  • Some basic understanding of docker (e.g knowing what containers, images, detached mode, ... are)
    → Official "Get Started" available here
  • Optional: If you're using the script, also install sudo and ip (usually pre-installed on most systems)

Quick start with script

  • Run
  • Type in two passwords -- one for the "normal" database user and one for root
  • Wait a few moments -- TestRail will be downloaded and set up

TestRail should be accessible via: http://localhost:8000

Finish the installation through the web UI (use the values printed by installer at the end)

Running Testrail using docker-compose

The compose file is configured via environment variables -- it's suggested to use a .env file. More about such an .env file is available here.

  • Create a .env file with at least the mandatory variables for:
    • DB_USER
    • DB_NAME
    • DB_PWD
  • Run docker-compose up (it will take a few minutes the very first time)
    You're done!

TestRail should be accessible via: http://localhost:8000

Re-enter the values you specified in the .env file when the TestRail installer asks for the database settings. To remove the instance, press Ctrl+C and then run docker-compose down.

Running TestRail with an external DB

If you'd like to just run TestRail and use a DB hosted on another server, in the cloud, starting TestRail is simple. In this case, only docker is needed (not 'docker-compose', as mentioned above).

docker run -d --name testrail -p 8000:80 -v $PWD/_opt:/opt/testrail -v $PWD/_config:/var/www/testrail/config testrail/apache:latest

How to use the compose files

The .env file

It's suggested to create a local .env file, to specify user or machine specific variables (more see here). Syntax is simple: e.g. 'HTTP_PORT=8000'

Environment variables can also be set directly in the shell with the same syntax and then using docker-compose.

Optional variables are:

Pre-populated databases and TestRails config.php

Via the DB_URL variable, it's also possible to provide a SQL-dump to be downloaded by the container, so TestRail is already pre-configured. For proper functionality, the config.php file needs to be provided. Simply copy it into the _config folder. Ensure that the values in the config.php file match the database settings for user and password, which are specified in the compose file for the db.

The Compose Files

General usage:

docker-compose up
docker-compose down

up starts the container; down stops everything. The docker-compose CLI reference can be found here.

Additional useful options:

  • -v (remove named volumes) This is important to remove temporary volumes after shutdown and is recommended to be used.
    If the volumes should not be purged, don't use this parameter. However, be aware that this might still cause some side effects.
  • -f (file) Can be used to specify a different compose file (by default docker-compose.yml is used)
  • -p (project) Has to be used if multiple TestRail instances should be started.
    Otherwise docker-compose with interact with an already running container. The name of the folder docker-compose is started in (in this case 'internal-docker') is used as a project name and is prepended to all spawned containers.

Recommendation: Use docker-compose down -v, as it removes named and anonymous volumes!

General remarks on the compose files

All compose files rely on additional volumes

  • testrail_root contains the installation and gets mounted to /var/www/testrail
  • testrail_opt contains uploaded files etc. and gets mounted to /opt/testrail
  • testrail_db contains the database and gets mounted to /var/lib/mysql.
  • testrail_config contains the config.php file, which configures TestRail and is mounted to /var/www/testrail/config

Containers are connected though a testrail bridged network. Start-order is important -- php needs to be first, followed by webserver and DB.

You can’t perform that action at this time.