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:
- 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 theconfig.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’ todb: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
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:
- Copy the
config.php
file to_config
. - If you want to keep attachments, reports, logs, and audit logs, create the folders
logs
,audit
,reports
, andattachments
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>
- 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:
- 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
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.