Quick start with script

Follow these steps:

1. Run quickstart.sh
2. Type in two passwords – one for the “normal” database user and one for root
3. Wait a few moments – TestRail will be downloaded and set up

TestRail should be accessible via the following URL: http://localhost:8000

Finish the installation through the web UI (use the values printed by installer at the end).

Once inside the installation wizard, you must paste the following path for Chrome Headless Shell:

• /usr/bin/chrome-headless-shell-linux64/chrome-headless-shell

Update Jira token configuration (Required for versions below 10.1.4)

If you are upgrading from a version earlier than 10.1.4, you must update the Jira token configuration file as part of this process.

1. Download the update files here.
2. Update the files:
   1. Locate the TestRail Server container name, for example testrail-docker-srv
   2. Run the command below to copy the new consts.php file into the container.

      docker cp patches/testrail-<version>/testrail/app/config/consts.php testrail-docker-srv:/var/www/testrail/app/config

   3. Set the correct file ownership.

      docker exec -it testrail-docker-srv \
      chown www-data:www-data /var/www/testrail/app/config/consts.php

Running TestRail using docker-compose

The compose file is configured via environment variables – it’s suggested to use a .env file. More about a .env file is available on the Docker env files documentation. 

1. First, create a .env file with at least the mandatory variables for:
   • DB_USER
   • DB_NAME
   • DB_PWD
   • DB_ROOT_PWD
2. Next, run docker-compose up (it will take a few minutes the very first time).
3. TestRail should be up! Access it via: http://localhost:8000
4. Re-enter the values you specified in the .env file when the TestRail installer asks for the database settings.
5. To remove the instance, press Ctrl+C and then run docker-compose down.

Environment variables

It’s suggested to create a local .env file, to specify user- or machine-specific variables (for more information, see the Docker env files documentation). The syntax is simple: e.g. ‘HTTP_PORT=8000’

Environment variables can also be set directly in the shell with the same syntax and then using docker-compose.

• DB_PORT
• HTTP_PORT
• HTTPS_PORT
• DB_URL (e.g. http://internal.yourcompany.com/5.7.sql)

Pre-populated databases and TestRail’s config.php

Via the DB_URL variable, it’s also possible to provide a SQL-dump to be downloaded by the container, so TestRail is already pre-configured. For proper functionality, the config.php file needs to be provided. Simply copy it into the _config folder. Ensure that the values in the config.php file match the database settings for user and password, which are specified in the compose file for the db.

Using Compose files

General usage

docker-compose up
docker-compose down

The argument up starts the container; while down stops everything. The docker-compose CLI reference can be found here.

Additional useful options:

Option	Description
-v (remove named volumes)	This is important to remove temporary volumes after shutdown and is recommended to be used. If the volumes should not be purged, don’t use this parameter. However, be aware that this might still cause some side effects.
-f (file)	Can be used to specify a different compose file (by default docker-compose.yml is used)
-p (project)	Required if multiple TestRail instances should be started. Otherwise, docker-compose will interact with an already running container.

The name of the folder docker-compose is started in (in this case, ‘internal-docker’) is used as a project name and is prepended to all spawned containers.

Recommendation: Use docker-compose down -v, as it removes named and anonymous volumes!

General remarks on the compose files

• All compose files rely on additional volumes:
• testrail_root contains the installation and gets mounted to /var/www/testrail
• testrail_opt contains uploaded files etc. and gets mounted to /opt/testrail
• testrail_db contains the database and gets mounted to /var/lib/mysql.
• testrail_config contains the config.php file, which configures TestRail and is mounted to /var/www/testrail/config

Containers are connected though a testrail bridged network. Start-order is important – php needs to be first, followed by webserver and DB.

Migrating & 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

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

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

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. Then you will need to follow these steps:

1. Locate the Apache docker container by running docker ps
2. Copy CONTAINER ID for testrail/apacheimage
3. Run docker exec -it <container_id> bash to enter docker container
4. Navigate to /var/www/testrail directory
5. Run php run.php update

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
6. Locate the Apache docker container by running docker ps
7. Copy CONTAINER ID for testrail/apache image
8. Run docker exec -it <container_id> bash to enter docker container
9. Navigate to /var/www/testrail directory
10. Run php run.php update

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.