Prerequisites
- Docker Host version 1.6+ has been installed on the machine where you are deploying qTest components. Ports 53 and 6783 on this machine need to be exposed if you are deploying with clustering model
- For CentOS 7.X+ or Ubuntu 14.04+ machines: Docker requires a 64-bit installation and your kernel must be at least 3.10
- Please follow these instructions to install Docker on your machine
- Docker Client has been installed. You will need to execute the deployment shell scripts in this instruction using the tool
- Docker Host is accessible using Docker Host
- Docker Host's configuration needs to satisfy qTest's recommended hardware requirement
»Deploy qTest components
-
»Deploy all components on the same machine
-
»Deploy all components on separate machines with a Load Balancer
»Configure qTest
»Import qTest Licenses
»Configure qTest Sessions and qTest Insights
»Miscellaneous & Troubleshooting
Deploy qTest components
You can download qTest Docker Deployment version 2.2 package here. It will deploy these prerequisite applications and qTest components on your machines:
Application name | Application code
(You will need to pass the application codes to --app parameter when deploying) |
---|---|
Redis | redis |
RabbitMQ | rabbitmq |
MySQL | mysql |
ElasticSearch | elasticsearch |
Postgres | postgres |
Poseidon | poseidon |
qTest | qtest |
qTest's Load Balancer | qtestlb |
qTest Sessions | sessions |
qTest Sessions' Load Balancer | sessionslb |
qTest Insights' Service | qmapservice |
qTest Insights' Web Application | qmapweb |
qTest Insights' Load Balancer | qmaplb |
You can either deploy all of these applications and components in the same machines or in separate machines with a load balancer
Deploy all components on the same machine
- Access to your machine where Docker Client has been installed using root or a user which has been added to docker user group
- Download the qTest package using wget or curl
$ wget https://qtest-storage.s3.amazonaws.com/docker/deployment/docker-deployment-2.2.tar.gz
- After qTest Docker Deployment package has been downloaded, extract it
$ tar -zxf docker-deployment-2.2.tar.gz
- Access to the extracted directory
$ cd docker-deployment-2.2
- Configure the bundle before deploying
- To deploy all components with default configurations, execute the following command
If your license package is Elite, the qtest-url and sessions-url are required in the command
$ ./configure --qtest-url "[qTest URL]" --sessions-url "[Sessions URL]"
Eg:
$ ./configure --qtest-url "http://192.168.76.235/" --sessions-url "http://192.168.76.235:8080/"
- To deploy all components with custom configurations, review the list of available parameters here and pass in the desired parameters when executing the command. For example:
$ ./configure --qtest-url "[qTest URL]" --sessions-url "[Sessions URL]" --ssl-key "[path_key]" --ssl-cert "[path_cert]" --ssl-ca "[sign_cert]"
Eg:
$ ./configure --ssl-key "/etc/pki/tls/private/mydomain.key.pem" --ssl-cert "/etc/pki/tls/certs/mydomain.crt.pem" --ssl-ca "/etc/pki/tls/certs/ca.crt.pem" --qtest-url "https://mydomain.com/" --sessions-url "https://mydomain.com:8443"
- To deploy all components with default configurations, execute the following command
- Start the deployment process
$ ./startup
- The script will download the application images and qTest components to the Docker Host. It may take couple of hours depending on your network connection
- After the deployment process completes, please access to qTest via your browser to configure it following this instruction
Deploy all components on separate machines with a Load Balancer
IMPORTANT:
- Deploying each qTest component requires that its prerequisite components/applications have been deployed and started in advance, as described in the table below
qTest Component Prerequisite Applications/Components qtest redis, rabbitmp, mysql qtestlb qtest sessions qtest, elasticsearch, postgres sessionslb sessions qmapservice qtest, sessions, poseidon qmapweb qmapservice qmaplb qmapweb - You can define your deployment structure. In this document, we will deploy qTest components in 4 machines:
- Machine 1: redis, rabbitmq, mysql, elasticsearch, postgres
- Machine 2: qtest, sessions
- Machine 3: qtest, sessions
- Machine 4 (the load balancer): qtestlb, sessionslb, poseidon, qmapservice, qmapweb, qmaplb. You can combine Machine 3 and Machine 4
On Machine 1
- Access to your machine where Docker Client has been installed using a user which has been added to docker user group
- After qTest Docker Deployment package has been downloaded, extract it
$ tar -zxf docker-deployment-2.2.tar.gz
- Access to the extracted directory
$ cd docker-deployment-2.0
- Configure the bundle before deploying
- Specify which components/applications to be deployed on Machine 1 in parameter --apps. They will be deployed sequentially as specified in the parameter
- You can optionally change the default configuration by running the command and passing in parameters. View available parameters here
Important: Do not pass any value in parameter --cluster
$ ./configure --apps "redis rabbitmq mysql elasticsearch postgres"
- Start the deployment process
$ ./startup
- The script will download the application images and qTest components to the Docker Host. It may take couple of hours depending on your network connection
On Machine 2 and Machine 3
- Access to your machine where Docker Client has been installed using a user which has been added to docker user group
- After qTest Docker Deployment package has been downloaded, extract it
$ tar -zxf docker-deployment-2.2.tar.gz
- Access to the extracted directory
$ cd docker-deployment-2.0
- Configure the bundle before deploying
- Specify which components/applications to be deployed on Machine 1 in parameter --apps. They will be deployed sequentially as specified in the parameter
- You can optionally change the default configuration by running the command and passing in parameters. View available parameters here
Important:
- --qtest-url, --sessions-url and --cluster parameters are required
- --qtest-url includes the IP or the host name of the machine where deploy qTest's load balancer (it is Machine 4 in this case) and the qTest port
- --sessions-url includes the IP or the host name of the machine where deploy qTest Sessions' load balancer (it is Machine 4 in this case) and the qTest Sessions port
- For --cluster parameter, pass in the IP of Machine 1
$ ./configure --apps "qtest sessions" --qtest-url "[qTest URL]" --sessions-url "[Sessions URL]" --cluster [Machine 1's IP]
Eg:
$ ./configure –apps “qtest sessions” --qtest-url "http://192.168.74.14/" --sessions-url http://192.168.74.14:8080/ --cluster “192.168.74.11”
- Start the deployment process
$ ./startup
- The script will download the application images and qTest components to the Docker Host. It may take couple of hours depending on your network connection
On Machine 4
- Access to your machine where Docker Client has been installed using a user which has been added to docker user group
- After qTest Docker Deployment package has been downloaded, extract it
$ tar -zxf docker-deployment-2.2.tar.gz
- Access to the extracted directory
$ cd docker-deployment-2.0
- Configure the bundle before deploying
- Specify which components/applications to be deployed on Machine 4 in parameter --apps. They will be deployed sequentially as specified in the parameter
- You can optionally change the default configuration by running the command and passing in parameters. View available parameters here
Important:
- --qtest-url, --sessions-url and --cluster parameters are required
- --qtest-url and --sessions-url are required to be the same across Machine 2, Machine 3 and Machine 4
- --qtest-url includes the IP or the host name of this machine and the qTest port
- --sessions-url includes the IP or the host name of this machine and the qTest Sessions port
- For --cluster parameter, pass in the IP of Machine 1
$ ./configure --apps "qtestlb sessionslb poseidon qmapservice qmapweb qmaplb" --qtest-url "[qTest URL]" --sessions-url "[Sessions URL]" --cluster [Machine 1's IP]
Eg:
$ ./configure –apps “qtestlb sessionslb poseidon qmapservice qmapweb qmaplb” --qtest-url "http://192.168.74.14/" --sessions-url http://192.168.74.14:8080/ --cluster “192.168.74.11”
- Start the deployment process
$ ./startup
- The script will download the application images and qTest components to the Docker Host. It may take couple of hours depending on your network connection
After the deployment process completes on all machines, please access to qTest via your browser to configure it following this instruction.
C. Available parameters to configure the deployment
Parameter | Required | Default value | Description |
---|---|---|---|
cluster | No | Only use it in case you are deploying qTest components on separate machines as described above. | |
apps | Yes | redis rabbitmq mysql qtest qtestlb elasticsearch postgres sessions sessionslb poseidon qmapservice qmapweb qmaplb | The list of qTest components and applications and their sequence in which they will be deployed on the machine. |
ssl-key | No | In case you are using SSL connection, specify the path to the private key on the Docker Host | |
ssl-cert | No | In case you are using SSL connection, specify the path to the certification on the Docker Host | |
ssl-ca | No | Specify the path to the certification of the authority on the Docker Host | |
qtest-url | No | http://[qTest server IP]:[qtest-http port]
See qtest-http parameter below |
Define the URL by which users can access qTest via their browser
* NOTE: If you are using qTest Elite license, you will need to define this value when deploying qTest Insights components. |
qtest-http | No | 80 | Define the http port by which users can access to qTest from their browsers |
qtest-https | No | 443 | Define the https port by which users can access to qTest from their browsers |
sessions-token | No | This token is used for qTest Sessions to connect to qTest. If you are migrating from qTest OnDemand to OnPremise, you can find the token in qTest Resources page. If you use qTest OnPremise from the start, ignore this parameter. | |
confdir | No | /etc/qasymphony | The directory on the Docker Host where different configurations are stored. It is recommended that you do not change the default value. |
datadir | No | /var/lib/qasymphony | The directory on the Docker Host where data files such as database files and attachments are stored. It is recommended that you do not change the default value. |
logdir | No | /var/log/qasymphony | The directory on the Docker Host log files are stored. It is recommended that you do not change the default value. |
sessions-url | No | http://[Sessions server IP]:[sessions-http port]
See session-http parameter below |
Define the qTest Sessions URL.
* NOTE: If you are using qTest Elite license, you will need to define this value when deploying qTest Insights components. |
sessions-http | No | 8080 | Define qTest Sessions' http port |
sessions-https | No | 8443 | Define qTest Sessions' https port |
qmapweb-http | No | 7080 | Define qTest Insights' http port |
qmapweb-https | No | 7443 | Define qTest Insights' https port |
Configure qTest
Creating Site Administrator Account
The Site Administrator account is compulsory and will be used to initiate the very first and essential activities on any qTest OnPremise sites, including creating projects, inviting users, assigning user profiles, purchasing licenses, etc...
Open your browser and access to qTest using the URL as configured when you installed qTest. If you did not change the default qTest URL and port, it is http//:[qTest Server IP]:80 or https//:[qTest Server IP]:443, in which [qTest Server IP] is the IP of the machine where qTest was installed.
At the first time log into qTest OnPremise, you will be directed to the Site Administrator account creation form. To start setting up this account, simply enter details into the form as illustrated below:
Organization name | This data is needed to create the root folder where all projects within a qTest site will be placed under. |
First name & Last name | Specify the first name and last name of the Site Administrator, used for selection/task assignments when working in qTest. |
Login email | Specify the email address of the Site Administrator used for logging. This must not be an organizational email address, but must be a valid email address (e.g.: address@mail.com). |
Password | Enter password and confirm the password again. This password must have 8-16 characters and contain at least 1 letter and 1 digit (e.g.: qtestadmin123). |
Setting Up Email Server
HINT: This step is not required at this stage, you can skip it but email notifications will not be sent when inviting new users into your site. It’s strongly recommended to complete this step before proceeding if you have an email server already up & running. You can come back anytime later to set up your SMPT email server if needed.
Once the Site Administrator account has been successfully created, you will be taken to the Email Server Setting form. This email server is required to send outgoing emails to users when certain events is triggered inside qTest (inviting users, deactivating/reactivating accounts, assigning tasks, editing items, subscribing users to items, etc..)
To set up a new email server for automatic notifications, complete the form as follows:
Host name |
Specify the hostname or IP address of your SMTP mail server. E.g.: smtp.yourcompanyname.com Some popular SMTP email server’s hostnames:
|
SMTP port (optional) |
Specify the SMTP port number, usually 25 for SMTP or 465 for SMTPS. Leave this field blank to use 25 as the default port. Some popular SMTP email server’s port:
|
Security protocols | Specify what security protocol your SMTP email server is using |
Security protocols | Specify what security protocol your SMTP email server is using |
From email address | Specify the email address used in the “Form” field in every outgoing email. This email address must be also configured and approved to send outgoing emails on this email server. |
Username & password (Optional) |
Enter password and confirm password if the SMPT email server requires authentication. For free SMTP services, username is your full email address itself. E.g.:yourname@gmail.com |
Import qTest Licenses
To activate your qTest application, you will need to import qTest license.
In qTest administration, select tab LICENSES - USERS. From there, you have 2 options:
- Click on Purchase licenses to purchase new licenses and then import them to your qTest
- If you already have a license file, click on Choose license file to import your licenses
IMPORTANT: If you have deployed qTest on multiple machines, please restart them as in the same sequence as when you deployed after importing licenses successfully.
Once the Site Administrator account has been successfully created, you will be taken to the Email Server Setting form. This email server is required to send outgoing emails to users when certain events is triggered inside qTest (inviting users, deactivating/reactivating accounts, assigning tasks, editing items, subscribing users to items, etc..)
Configure qTest Sessions and qTest Insights
- Login to your qTest using a site admin account. Access to site administration section
- Select tab System Configuration
- In Session Manager section, update eXplorer API Host. Input sessions-url:sessions-http or sessions-url:sessions-https as you deployed qTest Sessions
- In qTest Insights section, update qTest Insights Web URL. Input the IP or host name of the machine where you deployed qmaplb and qmap-http or qmap-https
Do not change qTest Insights Service URL
Miscellaneous & Troubleshooting
Check network ports
For Windows
You can check for which ports are being used by the following steps.
- Open a command prompt window (as Administrator): From "StartSearch box", enter resmon.exe
- On tab Network, expand Listening ports
For Linux
You can check for which ports are being used by the following command:
# netstat -npult
Reconfigure Deployed Components
- Access the machine where the Docker Client has been installed through a user that was added to the Docker user group
- Access the directory where the deployment scripts are located (Eg: docker-deployment-x.x)
- Shut down the applications/components which were deployed in the Docker Host:
$ cd docker-deployment-x.x $ ./shutdown $ ./weave stop
- Execute configure command and pass in the parameters to change the configurations. View available parameters here
- In order to change qTest / Sessions / qTest Insights port
$ ./configure --qtest-url "[qTest URL]" --sessions-url "[Sessions URL]" --qtest-http [qTest http port] --qtest-https [qTest https port] --sessions-http [Sessions http port] --sessions-https [Sessions https port] --qmapweb-http [qTest Insights http port] --qmapweb-https [qTest Insights https port]
For example:
$ ./configure --qtest-url "https://mydomain.com/" --sessions-url "https://mydomain.com:8443" --qtest-http 80 --qtest-https 443 --sessions-http 8080 --sessions-https 8443 --qmapweb-http 7080 --qmapweb-https 7443
- In order to enable SSL certificate, run these commands:
-
$ ./configure --qtest-url "[qTest URL]" --sessions-url "[Sessions URL]" --ssl-key "[path_key]" --ssl-cert "[path_cert]" --ssl-ca "[sign_cert]"
For example:
$ ./configure --ssl-key "/etc/pki/tls/private/mydomain.key.pem" --ssl-cert "/etc/pki/tls/certs/mydomain.crt.pem" --ssl-ca "/etc/pki/tls/certs/ca.crt.pem" --qtest-url "https://mydomain.com/" --sessions-url "https://mydomain.com:8443"
Then deploy Docker using the configuration:
$ ./startup
Backup
- Access your Docker host(s) through a user which was added to Docker user group
- Shutdown qTest
$ cd docker-deployment-x.x $ ./shutdown
- Run the following command to create a backup file in the Docker Host
$ ./backup
It will backup qTest on Docker host and save it as yyyy-mm-dd.tar.gz, in which yyyy-mm-dd is the date when the backup file was created.
- In case you want to backup and then download the backup file from the Docker host to your local machine, run this command
$ ./backup pull
It will download yyyy-mm-dd.tar.gz, in which yyyy-mm-dd is the date when the backup file was created, to your current directory.
Restore
- Access your Docker host(s) through a user which was added to Docker user group
- Run this command:
$ cd docker-deployment-x.x $ ./restore yyyy-mm-dd
- You can use yyyy-mm-dd to restore from a specific date when the backup file was created
- If yyyy-mm-dd is omitted in the command, the most recent backup file will be restored by default
- If you want to restore from a backup file which was downloaded to your local machine, run this command and pass in the file path
$ ./restore [path to yyyy-mm-dd.tar.gz]