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 linuxhint.com 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.)
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!

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/');

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!

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

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.