Prerequisites

To install a XQual Server from scratch, you'll need a Linux Server or a Windows server with a network connection, enough storage and memory. For more details check the minimal requirements.

Install Tomcat

A Servlet Container is web-server able to run web services and web sites. It will be used to host:

• the XQual Server,
• the XQual Web Application,
• the REST-API server,
• the Jira plugin front-end (necessary only if you use Jira and wish a both-way integration),
• the SSO service

Please click on the appropriate option below:

Install the Database Server

Before installing the software, please ensure you have enough physical storage on the database server to host all the data that you're going to create.

Of course, you can also choose to install the database server on teh same physical machine as teh one hosting Tomcat.

Please click on the appropriate options below:

Install XQual

This is where we are going to install XQual in Tomcat.

Please click on the appropriate option below:

Configure XQual

Database

Upload the JDBC drivers (only if using SQL Server or Oracle - less advised)

Please click on the appropriate option below:
The Database server is...

Install a database server management client

A this stage, we strongly suggest to install a tool so that you can manage your Database Server remotely.

To do so, you can install:

• either a web management tool (i.e. PhpMyAdmin) on the server and connect from any client using a simple browser
• or a Database management tool (i.e. SQLyog) on any client (NOT the server!). You can install it on your own personal computer as it's very light.

In the following we'll use SQLyog Community Edition (to connect to a MySql/MariaDb Database Server) as it's free, light to install, very simple to use and powerful at the same time (but you can use any another tool such as Toad if you prefer).

This must be installed on your computer, not on the server!

• Download SQLyog Community Edition from https://github.com/webyog/sqlyog-community or directly from our own repository:
  SQLyog Community Edition for Windows 32bits
  SQLyog Community Edition for Windows 64bits
  
  
• Execute the setup program (i.e. SQLyog-12.0.9-0.x64Community.exe)
  
  Choose the default options except when specified.
  
  
  
  
  
  
  
  
  
  
• Execute SQLyog and connect to the remote Database Server:
  
  Click on the Create a new connection button
  
  
  Provide a name for that connection
  
  
  Provide the IP address (or name) of the database server as well as the credentials to connect as root on the remote Database Server (i.e. rootpwd)
  Test the connection, Save it and Connect
  
  
  
  
  You're now connected to your remote database server and you can manage it.
  

Create an empty database and an account to access it

• Keep the SQLyog connection open
  
  Select the Database > Create Database menu item
  
  
  Provide a name for the database: xstudio_db
  
  
  You have now a new empty xstudio_db database
  
  
  Open the User Manager
  
  
  Create the user xstudio (ensure you have % selected in the Host combobox!)
  and provide a password for this user (IMPORTANT: set it initally to xstudiopwd - you'll be able to change it later!)
  
  
  Open the User Manager
  
  
  Grant all the rights to xstudio@% on the newly created xstudio_db database
  
  
  

You have now a remote Database Server up and running, including an empty xstudio_db database accessible by the user xstudio from ANY computer.

For security reason, this xstudio account has rights only on the xstudio_db database.

XQual will internally query the database only with this account.

Server Settings

Update the server settings

• Update the server configuration:
  
  • On Linux: edit /var/lib/tomcat8/webapps/xqual/xstudio.conf
  • On Windows: edit C:\Program Files (x86)\Apache Software Foundation\Tomcat 8.0\webapps\xqual\xstudio.conf
  
  ...and update the following entries:
  
  

  Field	Description
  Database server type database.type	This indicates which database server you're using: MySql MariaDB Oracle SQL Server
  driver jar path database.driver.jarpath	This indicates where XQual can find the JDBC driver to connect to the database. This field must indicates the relative path from <Install_folder>\bin\jdbc folder to the jar file. MySql:  mariadb-java-client-1.1.5/mariadb-java-client-1.1.5.jar (we advise using the MariaDb JDBC driver even with MySql) MariaDB:  mariadb-java-client-1.1.5/mariadb-java-client-1.1.5.jar Oracle:  oracle-11g-R2/ojdbc6.jar SQL Server:  sqljdbc_3.0/enu/sqljdbc4.jar
  driver class path database.driver.classpath	Classpath to instantiate the driver from the JAR file. MySql:  org.mariadb.jdbc.Driver MariaDB:  org.mariadb.jdbc.Driver Oracle: oracle.jdbc.driver.OracleDriver SQL Server: com.microsoft.sqlserver.jdbc.SQLServerDriver
  database server database.server	This indicates the IP address or the name of the database server.
  database name database.name	The name of the database (i.e. xstudio_db)
  connection template database.connection.template	Connection template to use the JDBC driver. WARNING: do NOT replace database_server and database_name fields in the connection template. They will be automatically replaced by the system with what you specified in database server and database name fields. For instance: MySql:  jdbc\:mysql\://database_server:3306/database_name MariaDB:  jdbc\:mysql\://database_server:3306/database_name Oracle:  jdbc\:oracle\:thin\:@//database_server:1521/database_name SQL Server: jdbc\:sqlserver\://database_server;databaseName=database_name; Do not forget the '\' character to escape any ':' character in this template.
  username database.connection.username	xstudio
  password database.connection.password	560B599C2331BE79C3ADD6621DBE8BDC (encrypted version of xstudiopwd which is the initial password of the xstudio db account)
  Max number of connections (default 64) database.max_number_connections	This defines how many connections can be opened by each client. Usually, this never exceeds 5. For instance: 32

  You must also provide information how to connect to the REST API:
  

  Field	Description
  REST API base url rest_api.base_url	This indicates the bae URL pointing to the REST API (i.e. http://<Tomcat server name or IP address>:8080/xqual/api)br/> Do not forget the '\' character to escape any ':' character in this template.
  REST API default username rest_api.default_username	admin
  REST API default password rest_api.default_password	14594A028745E255AA16A9D6D37D8D61 (encrypted version of password which is the initial password of the admin XQual user)

  
  You can leave all the other setting as-is for now.
  
  At this point, you can check you have those critical settings set similarly to:

  ...
  database.connection.accept_any_certificate=0
  database.connection.certificate=
  database.connection.password=560B599C2331BE79C3ADD6621DBE8BDC
  database.connection.template=jdbc\:mysql\://database_server/database_name
  database.connection.username=xstudio
  database.driver.classpath=org.mariadb.jdbc.Driver
  database.driver.jarpath=lib/mariadb-java-client-1.7.4.jar
  database.max_number_connections=64
  database.name=xstudio_db
  database.server=my_db_server.domain.com
  database.type=MariaDB
  ...
  rest_api.base_url=http\://my_tomcat_server.domain.com:8080/xqual/api
  rest_api.default_password=D6C956C2925A946E
  rest_api.default_username=admin
  ...
  

  NOTE: if your database server is not hosted in your private network, you can also configure your server so that the servlet connects through ssh.
  In that case, you do not need to open your database server port (i.e. 3306 if you're using MySql) which will facilitate the install if your company have strict firewall rules.
  
  In addition, if you do so, all the communications are then encrypted which is great in terms of security/confidentiality if you're connecting to a remote server and do not use VPN.
  
  This is a quite rare setup as usually both Tomcat and the database server are hosted on the same network. The communication between the end users and the server are anyway secured with SSL. However, if you're interested in encrypting also the communication between the server and the database server, you can find all the details about how to configure your system with ssh in the connecting through ssh section of the documentation.
  
  
  • The server will need a few additional libraries to be able to generate reports.
    
    On each system it can be pretty different but on a headless fedora server for instance you will need
    to install those libs this way:
    
    dnf install -y atk
dnf install -y at-spi2-atk
dnf install -y cups-libs
dnf install -y libdrm
dnf install -y libXcomposite
dnf install -y libXdamage
dnf install -y libXrandr
dnf install -y mesa-libgbm
dnf install -y libxkbcommon
dnf install -y pango
dnf install -y alsa-lib

    
  • Ensure everything in the converthtml folder is executable
    chmod a+x /var/lib/tomcat8/webapps/xqual/converthtml
    
    
  If you're using SELinux (a Linux security module that makes it possible to define a mandatory access control policy for the elements of the system), you must authorize Tomcat to connect to the database.
  To do this, run the command: setsebool -P tomcat_can_netork_connect_db 1

Restart the tomcat server

• Please click on the appropriate option below:

  The server is linux computer

  Restart Tomcat
  To ensure that the server took into account the last changes properly, restart Tomcat.
  
  With Yum (Fedora, Cent OS, Red Hat):
  systemctl restart tomcat or service tomcat restart on older systems
  
  With Apt-get (Debian, Ubuntu etc.):
  service tomcat8 restart
  
  For debugging purposes, you can have a look at Tomcat's log to check everything started properly without error. The log file is generally located in /var/lib/tomcat8/logs/catalina.out. On recent systems you might get it using the command journalctl -u tomcat.
  
  

  The server is a Windows computer

  Restart the Apache Tomcat 8.0 Windows Service
  
  

Configure the XAgent's JNLP access (only necessary if you have automated tests)

Please click on the appropriate option below:

Install a Tomcat watchdog (only if you need to manage server configuration and restart Tomcat from the UI)

If you want to authorize your XQual admin to modify the server settings and restart Tomcat directly from the UI, you will need to create and install a watchdog script that will check regularly the presence of a file /var/lib/tomcat8/webapps/xqual/tomcat_watchdog.flag. If that file exists, the watchdog will need to:

• Immediately rename the file tomcat_watchdog.flag to tomcat_watchdog.flag.processing
• Wait at least 3 seconds
• Restart Tomcat (for instance with Systemctl restart tomcat
• delete the file tomcat_watchdog.flag.processing

Here is a good example:

#!/bin/sh

DATE=`date +%y_%m_%d_%H_%M` 
FLAG="/var/lib/tomcat8/webapps/xqual/tomcat_restart.flag" 
LOG="/var/lib/tomcat8/webapps/xqual/tomcat_restart.log" 

if [ -f "$FLAG" ]; then 
   mv "$FLAG" "$FLAG.processing" || exit 0 
	
   echo "indicating that the restart is about to start at '$DATE'..." >> "$LOG" 
	
   # wait 3 seconds so that the restartServer() REST API has time to send the response 
   sleep 3
	
   echo "Restart requested at '$DATE'" >> "$LOG" 
	
   if systemctl restart tomcat; then 
      echo "Restart successful at '$DATE'" >> "$LOG" 
      rm -f "$FLAG.processing" 
   else 
      echo "Restart failed on '$DATE'" >> "$LOG"
   fi 
fi

This script must be called every 20 seconds.
It can be installed in /usr/sbin for instance and called regularly using the cron daemon:

* * * * * root /usr/sbin/tomcat_watchdog.sh
* * * * * root sleep 20; /usr/sbin/tomcat_watchdog.sh
* * * * * root sleep 40; /usr/sbin/tomcat_watchdog.sh

You may need to adapt the script to the OS/distrib/shell version you're using.

Check the install

Now that the install is completed, let's check your server is fully operational.

Start XQual from any computer

• Open the URL: http://<Tomcat server name or IP address>:8080/xqual/xstudio.web/ and login
  
  
• Authenticate to XQual using the default credentials:
  
  

  Username:	admin
  Password:	password

  
  
  
  
• XQual's GUI appears on the screen.
  

Try the REST API

You can access programmatically the XQual REST-API server using the following URL:
http://<Tomcat server name or IP address>:8080/xqual/api?<query>

For instance, you can browse the URL:
http://<Tomcat server name or IP address>:8080/xqual/api?command=getInfo

This should return a json string containing information about the server similar to:
{"application_title":"XQual","application_copyright":"(c) copyright XQual",
"application_version":"3.0sp8", "database_schema_version":"78"}

For more information on the types of queries you can post please refer to the REST API documentation.

Request a license

At this stage, you can ask for your FREE trial license!