Installation on Docker: Migrating and upgrading TestRail

Running TestRail within Docker containers

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

TestRail uses docker-compose to run the individual services necessary 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 on the docker env files documentation – 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.

The site provides a good overview of how to use env-variables in bash.

Migrating from an existing TestRail Server installation to containers

Using a database within containers

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

  1. 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 – use the respective internal docker subnet instead of ‘%’ for security hardening.)
  2. Copy the whole content of /var/lib/mysql to the _mysql folder and the config.php file to _config.
  3. 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.
  4. 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/');
  5. 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>
  6. Run docker-compose up -d

That’s it — you’re done!


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:

  1. Copy the config.php file to _config.
  2. If you want to keep attachments, reports, logs, and audit logs, create the folders logsauditreports, and attachments in the _opt folder, and copy the content from the old location to the newly created folders.
  3. 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/');
  4. 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>
  5. Run docker-compose up -d

That’s it — you’re done!


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:
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, below.

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:

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


Create a backup of the folders containing the database and the folder which contains the logs, reports, attachments, and audits. 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

  • DB_URL
  • DB_PWD

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.


If you’re upgrading from 7.0 to either 7.4 or above, you need to run the migration script as documented here: Upgrading TestRail. The recommended upgrade sequence is:

  1. Install and configure Cassandra

  2. Install or upgrade TestRail

  3. Execute out the 7.0 or previous to 7.4 and up migration script

Was this article helpful?
0 out of 5 found this helpful