Home

Running TestRail within Docker containers

Requirements

• 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 quickstart.sh script, also install sudo and ip (usually pre-installed on most systems)

Getting started

Please have a look at the Readme in the Github repo.

TestRail uses docker-compose to run the individual services neccesary and link the containers together.
To start/stop TestRail, these two commands do the job (execute them in the root folder of the repo):

docker-compose up
docker-compose down

To start the containers in detached mode, just add a -d parameter: docker-compose up -d The docker-compose files contain a number of variables with pre-assigned default values. To assign custom values for these variables, either create a .env file (as described here -- it's a simple text file with a VAR=VALUE syntax). Otherwise, it's also possible to provide the env-variables via command line like export HTTP_PORT=8008 && docker-compose up -d. This site provides a good overview how to use env-variables in bash.

Migrating from an existing TestRail Server Installation to Containers

Using a Database within Containers

If you've ran a dedicated DB just for TestRail, it makes sense to also run the DB in a container. Follow these steps to upgrade:

• Check the privileges of the mysql user before migrating -- if a user was created with '@localhost' (restricting access to "from localhost only"), you need to create a new user with sufficient right to allow remote connections
  • Access the DB with mysql -p and list all users + host: SELECT user, host FROM mysql.user;
  • If the TestRail user has 'localhost' or some IP in the 'host' column (and not '%'), a new user needs to be created
    • CREATE USER 'testraildocker'@'%' IDENTIFIED BY 'newpassword';
    • GRANT ALL ON testrail.* TO 'testraildocker'@'%';
      (The '%' allows remote connections from any IP. If you know your docker subnet -- usually 172.16.255.255 -- use the respective internal docker subnet instead of '%' for security hardening.)
• Copy the whole content of /var/lib/mysql to the _mysql folder and the config.php file to _config.
• If you want to keep attachments, reports, logs, and audit-logs, create the folders logs, audit, reports, attachments in the _opt folder and copy the content from the old location to the newly created folders.
• Edit the config.php file and change the 'DB_HOSTNAME' to db:3306.
• Also change the LOG_PATH and the AUDIT_PATH to:

    define('LOG_PATH', '/opt/testrail/logs/');
    define('AUDIT_PATH', '/opt/testrail/audit/');

• If you'd like to use a specific port to access TestRail, create a .env file (more here) and specify the port via HTTP_PORT=<portNumber>

Run docker-compose up -d

You're done :-)

Please note: Also change the paths for 'attachments' and 'reports' under TestRail->Administration->Site Settings to: /opt/testrail/attachments and /opt/testrail/reports

Using an External Database

If you're using an 'external' database server, leave the DB server as it is and follow these steps:

• Copy the config.php file to _config.
• If you want to keep attachments, reports, logs, and audit-logs, create the folders logs, audit, reports, attachments in the _opt folder and copy the content from the old location to the newly created folders.
• Edit the LOG_PATH and the AUDIT_PATH in the config.php file to:

    define('LOG_PATH', '/opt/testrail/logs/');
    define('AUDIT_PATH', '/opt/testrail/audit/');

• If you'd like to use a specific port to access TestRail, create a .env file (more here) and specify the port via HTTP_PORT=<portNumber>

Please note: Also change the paths for 'attachments' and 'reports' under TestRail->Administration->Site Settings to: /opt/testrail/attachments and /opt/testrail/reports

Upgrading TestRail (if you are already using containers)

Option 1 -- Quick 'n' dirty

Simply use the upgrade script: upgradeTestRail.sh
This will upgrade TestRail if you stayed with the default configuration created by the 'quickstart' script. If you're using custom locations for the DB-files, etc. use Option 2.

Option 2 -- Doing the upgrade step by step

To upgrade TestRail from an older to a newer version (e.g. 6.0.0 to 6.0.1), perform the following steps:

• Shut down the containers: docker-compose down -v
• (Optional) If you've specified a dedicated TestRail version in e.g. a .env file -- set the version you want to upgrade to.
• Pull the images: docker-compose pull
• Recommended: Create backups (see below)
• Start TestRail docker-compose up -d

Important: Create a backup of the folders containing the database and the folder which contains 'logs, reports, attachments and audit'. By default, these folders are _mysql and _opt in the local directory. Also create a copy of the config.php files located in _config.
You can also do a 'safe' upgrade by copying these three folders to a new location and then running docker-compose.

Advanced Topics

Apache vs. nginx and MySQL vs. MariaDB

TestRail currently officially supports Apache + MySQL. Feel free to give nginx and mariadb a try -- however, please note that this is not officially supported. For the case you find any issues with these two systems, please let us know, so we can get closer to a potential nginx/mariadb support in future.

Creating Backups

All containers are stateless, so they can safely be removed.
Relevant data is stored in local volumes -- by default in _config, _mysql, and _opt. Just create a backup of these folders.

Environment Variables

• TESTRAIL_VERSION

• OPT_PATH

• CONFIG_PATH

• MYSQL_PATH

• HTTP_PORT

• DB_PORT

• DB_URL

• DB_USER

• DB_PWD

• DB_NAME

• DB_ROOT_PWD

• TR_DEFAULT_TASK_EXECUTION

Building the Images Yourself

It's also possible to build the docker images by yourself. All Dockerfiles can be found in this folder. Build instructions are in the respective subfolders.