QMetry and Reports Installation on AWS (using RDS & ECR)
This guide describes how to install the QMetry database on Amazon Relational Database Service (RDS), the QMetry Test Management application, and QMetry Reports in a 3-tier architecture on AWS.
This installation requires MySQL v8.4.8 on AWS RDS and installs QMetry over Apache Tomcat 11.0.5 and Open JDK 17.0.2 in a Docker container.
Deployment Architecture
3 Tiers | Installations |
|---|---|
Server 1 | QMetry Application |
Server 2 | QMetry Reports |
AWS RDS 1 | QMetry Database |
AWS RDS 2 | QMetry Reports Database |
Prerequisites
Confirm every item in the Pre-requisites for QMetry Application and Report Server Installation document. After that confirm the following:
Prerequisite | What to confirm |
|---|---|
Operating System | Linux - Ubuntu 24.04, and Amazon Linux 2023 |
Required commands | unzip, wget, curl, and vim commands are supported. |
Internet access | Internet access is required to download and install docker and QMetry installation images. |
Proxy Servers | No proxy blocks downloads from the internet. |
Server communication | The application and report servers can reach each other on the required ports. |
Open ports | Ports 80, 443, 8080 and 3306 are free on the relevant servers. |
Root access | Docker installation requires root user access. |
Disk space | The Docker and data directories have enough free space. |
Installation files | Get the |
In addition to this, ensure the following:
Four servers are required: two AWS RDS instances (one for the QMetry database and one for the Reports database), the QMetry application server, and the QMetry Reports server.
By default, Docker stores data under /var/lib/docker on the host machine. Make sure that /var/lib/docker and the QMetry data directory have enough disk space for your expected QMetry usage.
Application Server and Reports Server must have appropriate IAM roles assigned to communicate with various other AWS services like AWS ECR, AWS RDS, etc.
Required Ports
The following ports should be open:
Installation | Ports that need to be enabled and should be available for use |
|---|---|
AWS RDS - QMetry Application Database and QMetry Reports Databases | 3306 for both RDS |
QMetry Application | 80/443 |
QMetry Report | 80/443 and 8080 |
AWS EFS | 2049 |
AWS ElastiCache (if enabling the optional Redis Cache Cluster) | 6379 |
The QMetry application server must be able to reach the QMetry Reports server on port 8080. Both servers must be able to reach the Application RDS and Reports RDS endpoints on port 3306.
Configure AWS EC2 to authenticate with AWS ECR service
Install and configure AWS Credential Helper. If you want to use AWS IAM Role based authentication mechanism for ECR authentication from AWS EC2, then follow this step. Else, skip this step and make sure that you have done authentication with AWS ECR from QMetry and Report EC2 server before moving to the next step.
For more information, see Amazon ECR Docker Credential Helper on GitHub.
Placing QMetry and Report Docker Images on the AWS ECR
Get Docker Image and place it on ECR. Perform these steps from the machine from which Docker Hub Container Image Library | App Containerization is accessible. It is required to have docker tool installed on this machine. Also, make sure that you have credentials for the ECR. In this step, we will download QMetry and Report docker image from docker repository and push it to the ECR repository.
Follow the steps mentioned below.
Log in to Docker using the credentials received from QMetry support.
docker login
Pull the QMetry and Report docker images from docker repository.
docker pull qmetry/qmetry:latest docker pull qmetry/qmetry:reports_latest
Tag QMetry and Report Docker images with the ECR.
docker tag qmetry/qmetry:latest <ECR_Repo_Url>/qmetryapp:latest docker tag qmetry/qmetry:reports_latest <ECR_Repo_Url>/qmetryreport:latest
If you have set up and configured AWS Credentials Helper utility on EC2 servers, then skip this step and move to the next step.
docker login <ECR_Repo_Url>
If you have ECR credentials, then log in with ECR using it.
If you have AWS CLI installed and configured on EC2, then you can use the following method to do authentication with ECR.
aws ecr get-login-password --region <regionID> | docker login --username AWS --password-stdin <ECR_Repo_Url>
Push QMetry App and Report docker images to ECR.
docker push <ECR_Repo_Url>/qmetryapp:latest docker push <ECR_Repo_Url>/qmetryreport:latest
Create and Configure 2 RDS for QMetry Application Database and QMetry Reports Database
Create two RDS instances that share a common parameter-group family, one for the application database and one for the reports database.
Step 1. Create DB parameter groups
To create database parameter groups, do the following:
Go to AWS Management Console and open the Amazon RDS console.
In the navigation pane, select Parameter groups.
Select Create parameter group.
Parameter group family: Select mysql8.4 as DB parameter group family.
Group name: Provide the name of the new DB parameter group.
Description: Provide a description for the new DB parameter group.
Click Create.
Repeat these steps to create a second parameter group for the Reports RDS instance.
Step 2. Edit the parameter groups
To edit the parameter groups, do the following:
Open the parameter group that you created for the application database.
Set the following parameters, and then save your changes.
Parameter
Value
binlog_format
ROW
character_set_client
utf8mb4
character-set-client-handshake
0
character_set_server
utf8mb4
collation_server
utf8mb4_unicode_ci
group_concat_max_len
500000000
innodb_autoinc_lock_mode
2
innodb_thread_concurrency
10
log_bin_trust_function_creators
1
lower_case_table_names
1
max_allowed_packet
536870912
sql_mode
NO_ENGINE_SUBSTITUTION,STRICT_TRANS_TABLES,ERROR_FOR_DIVISION_BY_ZERO
thread_cache_size
200
innodb_log_buffer_size
536870912
innodb_log_file_size
1073741824
Open the parameter group that you created for the Reports database.
Set the following parameters, and then save your changes.
Parameter
Value
character-set-client-handshake
0
group_concat_max_len
500000000
innodb_autoinc_lock_mode
2
innodb_strict_mode
0
lower_case_table_names
1
max_allowed_packet
536870912
thread_cache_size
200
Step 3. Create the Application Database RDS
To create the RDS instance for the QMetry application database, do the following:
Create an RDS with MySQL database version 8.4.8
Enter the RDS instance name, user name, and password.
Select the Application DB Parameter Group from Step 2.
Start the service: RDS → Databases → Actions → Start.
Connect to the application RDS instance and run the following so MySQL bin logs survive restarts (required for dependable report sync):
call mysql.rds_set_configuration('binlog retention hours', 24);
Note
Save the Application RDS username, password, schema name, and endpoint. You will need them during installation.
Step 4. Create the Reports Database RDS instance
To create the RDS instance for the QMetry Reports database, do the following:
Create an RDS with MySQL database version 8.4.8
Enter the RDS instance name, user name, and password.
Select the Reports DB parameter group from Step 2.
Connect to the Reports RDS and create the analytics schema:
CREATE SCHEMA `qtmanalytics` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
Note
Save the Reports RDS username, password, schema name, and endpoint.
Install the QMetry Application
To install QMetry Application, do the following:
Note
Recommended: Back up the application data directory on a regular schedule. Periodic backups help prevent data loss if a disaster occurs.
The installation may take a while.
Connect to the QMetry application server. Upload the
QMetry_Linux_Installer_ECR.zipfile that you received from QMetry Support to the /opt directory, and then extract it:sudo su - cd /opt unzip QMetry_Linux_Installer_ECR.zip cd QMetry_Linux_Installer_ECR/
Run the installer.
chmod +x install.sh ./install.sh
Enter your response for the install prompt.
Options
Allowed Values
Default Value
Recommended Value
Do you want to make an online installation (Y/N)?
Y, y, N, n
Y
Y
Enter the docker credentials shared as a part of the installation package.
At the main installation menu, type 2 to install the application.
Enter docker repository URL: <input_ecr_url>.
If AWS server has appropriate permission to download docker image from the ECR, then installation process will move forward with the next step. Otherwise, it will prompt for adding correct authentication details for the specified ecr url.
Enter the EFS directory to store QMetry data such as attachments, licenses, imports, and exports. All QMetry application nodes must use the same shared directory.
Also, specify directory path for storing QMetry application's log files. This directory must not be shared across the multiple nodes of the QMetry application.
Options
Description
Example
Please enter QMetry application directory
Enter the EFS file system directory mounted for QMetry installation from the pre-requisites section above step 1.
/opt/qmetryapp
Please enter QMetry application's log directory (not shared)
Enter a dedicated, non-shared directory to store the application log files for monitoring and troubleshooting.
/home/QMetry_Linux_Installer_ECR_logs
Configure the following parameters.
Options
Details
Default Value
Example
Enter QMetry Database Hostname
Enter QMetry Database Host as DNS/IP Address
<RDS DB Endpoint>
Enter RDS DB Endpoint
Enter QMetry Database Port
Enter QMetry Database Port. If it is unchanged, use "3306" as the Database port.
3306
3306
Enter QMetry Database Schema
QMetry Application Database schema name.
qmetry
qmetry
Enter QMetryDatabase Username
Enter the RDS master username for the Application RDS.
-
RDS master username
Enter QMetry Database Password (root user)
Enter the RDS master password for the Application RDS.
-
QMetry@123
Enter QMetry User (admin) Email (admin user)
Enter QMetry user email address for Admin.
-
Enter QMetry User (admin) Password
Enter QMetry user password for Admin.
-
Admin@123
Enter Min. Heap Memory for the webserver
Enter Heap Memory in GB(s)
2
2
Enter Max. Heap Memory for the webserver
Enter Heap Memory in GB(s)
4
4
Enter QMetry Database Connection Pool Size
Enter Pool Size in number format
100
100
Verify the docker.
docker ps
Get the license and install it.
Evaluation: Use the evaluation license, valid for 30 days, that you received with the installation.
Commercial:
When you receive license.key, follow Steps to Apply License File.
QMetry Support needs your server's domain name and MAC address.
Run ip link show to find the MAC address of the network interface (for example, eth0). Email the MAC address and your server's domain name to [email protected].
Open the QMetry application in a browser at the following address, where you substitute your own value. http://<your IP address OR domain name>. Log in with the Default QMetry credentials.
Username: admin
Password: <user specified password in Step # 8 >
Your database is the Application RDS instance. QMetry installs with default minimum and maximum heap memory settings. You can adjust these settings to match your hardware configuration. For more information, see Additional Configuration.
Log in to the QMetry application and update the administrator profile.
Go to admin profile and click Edit.
In the email box, enter the administrator email address.
In the base URL box, enter your QMetry URL.
Click Update.
Configure additional Tomcat settings: QMetry installs with a default configuration for minimum and maximum heap memory. You can adjust these settings to match your hardware configuration. For EFS file system when creating an EC2 instancemore information, refer to Additional Configurations.
Install QMetry Reports
Note
If you have purchased Advanced Reporting, then you will need a separate server for installing QMetry Reports.
Steps to Follow for QMetry Report Installation
To install QMetry Reports on the second server, perform the following steps:
Wait for the script file to finish executing.
Options | Details | Example |
|---|---|---|
Enter Mysql Database Host IP / DNS Name (QMetry) | Enter the Application RDS endpoint. Enter the RDS master username for the Application RDS. | Specify QMetry App RDS DB Endpoint |
Enter Mysql Database Port (QMetry) | Enter Database Port of QMetry application. If it is unchanged, use "3306" as Database port. | 3306 |
Enter Mysql Database Schema (QMetry) | Enter Database schema name of QMetry application. | qmetry |
Enter Mysql Database Username (QMetry) | Enter Database username of QMetry application. | RDS master username |
Enter Mysql Database Password (QMetry) | Enter Database password of QMetry application. | QMetry@123 |
Enter Mysql Database Host IP / DNS Name (Reports) | Enter the Reports RDS endpoint. | Specify QMetry Reports RDS DB Endpoint |
Enter Mysql Database Port (Reports) | Enter Database Port of QMetry Report Database. If it is unchanged, enter "3306" as Database Port. | 3306 |
Enter Mysql Database Schema (Reports) | Enter Database schema name as “qtmanalytics“ for QMetry Reports Database. | qtmanalytics |
Enter Mysql Database Username (Reports) | Enter the RDS master username for the Reports RDS. | RDS master username |
Enter Mysql Database Password (Reports) | Enter Database password of QMetry Reports Database. | QMetryreports@!Nf0# |
Enter Port To Start SyncJob (Reports) | Reports Sync Job runs from this port - 8080. | 8080 |
Do you want to Run Force Sync Now? (y/n) | Enter y to sync all the QMetry data to Reports Database with the current script. Always enter y at the time of fresh reports install. | Y |
Connect to the report server. Upload the
QMetry_Linux_Installer_ECR.zipto the /opt directory of the Report server and extract it with the following commands.sudo su - cd /opt unzip QMetry_Linux_Installer_ECR.zip cd QMetry_Linux_Installer_ECR/
Run the reports installer.
chmod +x install.sh ./install.sh
Enter your response for the following prompt.
Options
Allowed Values
Default Value
Recommended Value
Do you want to make an online installation (Y/N)?
Y, y, N, n
Y
Y
Enter the docker credentials that were shared as part of the installation package.
At the main installation menu, type 3 to install reports.
Configure the reports parameters.
Options
Details
Default Value
Example
Enter Number of CPU's to allocate
Enter 3/4th of total memory available on the server." with "Enter three-quarters (75%) of the total memory on the server.
To check total CPUs, run the command : lscpu
4
6
Enter Memory to allocate in GB(s)
Entered memory would be used by the sync job while running full sync of data. Enter 3/4th of total memory available on the server. For example, if the memory on the server is 24 GB, enter 18.
4
18
After successful installation of QMetry Report, you will see the message "QMetry Report Installation is complete".
Note
In cases when you need to force sync to re-sync any missing data, just repeat step 6, and skip all parameter details (by hitting enter) and just enter y when prompted for a force sync.
Verify the docker.
docker ps
Restart the report services.
docker restart qmetry-reports
Wait for about 2 minutes before proceeding with the next step.
Log in to QMetry as the admin user and configure the Reports database connection.
Log in to QMetry with administrator credentials and go to Customizations.
Select Insight Configuration and open Database Configuration tab.
Under Database Configuration tab, enter the following details:
Host: Reports RDS endpoint.
Port: 3306
Username: Enter the RDS master username for the Reports RDS.
Password : <Enter Report database password>
Database Name: <Report DB schema specified during installation>
Select Test to confirm a successful connection, and then select Test & Save.
Set up the report data sync
On the Sync Data tab, set up the Report Data Sync from your reports server to QMetry Reporting.
Report Server URL: Enter your report server domain URL followed by port 8080. Confirm that port 8080 is open on the report server.
Select Test to confirm a successful connection and then select Test & Save.
Note
Run Sync Data the first time after you install QMetry reports installation. The time that the sync takes depends on the amount of data in QMetry. You can monitor sync progress and status in the interface. QMetry custom reports are not accessible while the sync runs. Run the sync only during off-peak hours.
Users can start using QMetry Reports when the sync is completed. QMetry remains available during this time.
Enabling Redis Caching Cluster (optional)
QMetry provides a capability for improving the overall performance and scalability even more by setting up Redis Caching Cluster. This step is optional. Follow the below steps to configure Redis Cache.
 |
Create a Redis cluster using Amazon ElastiCache. Use Redis OSS engine version 7.1 or later. QMetry supports Redis 7.0.10 and later.
AWS ElastiCache Redis Cluster should be accessible to all the EC2 servers of QMetry application for caching related communication and configuration.
Ensure port #6379 is opened for incoming connections in the security group to allow connections from AWS EC2.
Port #6379 should be free and not in use by other applications.
Configure Redis connection details in QMetry.
Log in to QMetry as the admin user. In the top-right corner, go to admin Profile, and click Edit.
In the Redis URL box, enter the ElastiCache endpoint and port, and then click Test. If the test fails, check the connectivity between the ElastiCache cluster and the QMetry, application EC2 servers.
After the test succeeds, click Update.
Install Automation API Features
Install the Automation API feature to enable automation API capabilities in your on-premises QMetry installation, including faster imports of automation result files. If you plan to use the Automation API to import test results into QMetry, see Installation for Automation API.
Get Support
If you encounter any issues during installation, create a ticket on the QMetry Support Portal or contact your sales representative.