Docker: Migrating and upgrading TestRail - TestRail

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 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 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 172.16.255.255 – use the respective internal docker subnet instead of ‘%’ for security hardening.)

  1. Copy the whole content of /var/lib/mysql to the _mysql folder and the config.php file to _config.
  2. 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.
  3. 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/');

  1. 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>
  2. Run docker-compose up -d

That’s it — you’re done!

info 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 logs, audit, reports, 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/');

  1. 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>
  2. Run docker-compose up -d

That’s it — you’re done!

info 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, 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

info Important: 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

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