Install XStudio Server

install server


Prerequisites

To install a XStudio 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:
  • XStudio (JNLP version),
  • XStudio.web (Web version),
  • REST-API web service that gives you the possibility to query the database programmatically
  • Jira plugin front-end (necessary only if you use Jira and wish a both-way integration)

Please click on the appropriate option below:

You can use the servlet container you prefer (there is no specific requirements about it) but on Linux platforms the most widely used is Apache Tomcat server.

The Install procedure may differ depending on the Linux distribution you're using but most of the time it will consist in these commands (executed as root):

Install Java

With Yum (Fedora, Cent OS, Red Hat):
yum update
yum install java-1.7.0-openjdk

with Apt-get (Debian, Ubuntu etc.):
apt-get update
apt-get install openjdk-7-jre

Install Apache Tomcat

With Yum (Fedora, Cent OS, Red Hat):
yum update
yum install tomcat
yum install tomcat-webapps
yum install tomcat-admin-webapps
chkconfig tomcat on
service tomcat start

with Apt-get (Debian, Ubuntu etc.):
apt-get update
apt-get install tomcat8
apt-get install tomcat8-admin
chkconfig tomcat8 on
service tomcat8 start

Configure Apache Tomcat

Edit (as root) the configuration file /etc/tomcat8/tomcat-users.xml and add the following entries:

<role rolename="admin"/>
<role rolename="admin-gui"/>
<role rolename="manager"/>
<role rolename="manager-gui"/>
<user username="tomcat" password="tomcatpwd" roles="admin,admin-gui,manager,manager-gui"/>
You can use the servlet container you prefer (there is no specific requirements about it) but on Windows platforms the most spread is Apache Tomcat.
Most of the time it will consist in just running the setup program (executed as Administrator):

Install Java

  • Install/Update Java directly from http://www.java.com/ or directly by downloading a setup program from our own repository:
    JRE 8 update 40 for Windows 32bits
    JRE 8 update 40 for Windows 64bits

  • When you are on the http://www.java.com/ page, just click on the Free Java Download button and follow the instructions.
    If you prefer installing from a setup program (i.e. jre-8u40-windows-i586.exe), you'll get similar screens.

    Choose the default options except when specified.

    java

    java

    jxpinstall.exe is a very small executable that will download then install the Java Runtime package
    java

    (these are the first screens you will see if you chose to install Java using a setup program)
    java java

    java java

    java java

    Untick the Restore Java security prompts
    java java

    java

    If you ask to verify the java version, you will be prompted to authorize the Java Detection applet to execute.
    Click Run.
    java

    java


Install Apache Tomcat

  • Download Apache Tomcat from http://tomcat.apache.org/

  • Execute the setup program (i.e. apache-tomcat-8.5.89.exe)

    Choose the default options except when specified.

    tomcat tomcat

    tomcat
    Select the Full install type

    tomcat
    Create an admin user (i.e. tomcat) and assign it a password (i.e. tomcatpwd).
    In the roles list, add manager.

    tomcat tomcat

    tomcat

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.

Please click on the appropriate options below:

On a Linux server, you can use MySql, MariaDb or Oracle.
Starting from XStudio v1.2, MySQL 5.0.3 is the minimum version required but more recent versions are preferred.
The Install procedure may differ depending on the Linux distribution you're using but most of the time it will consist in these commands (executed as root):

With Yum (Fedora, Cent OS, Red Hat):
yum update
yum install mysql-server
You will have to set the root password (i.e. rootpwd)

/usr/bin/mysql_secure_installation
Answer 'y' to all questions except "Disallow root login remotely?" where you need to answer 'n'

chkconfig mysqld on
service mysqld start

With Apt-get (Debian, Ubuntu etc.):
apt-get update
apt-get install mysql-server
You will have to set the root password (i.e. rootpwd)

/usr/bin/mysql_secure_installation
Answer 'y' to all questions except "Disallow root login remotely?" where you need to answer 'n'

chkconfig mysqld on
service mysqld start

To manually enable root access from remote machines:
mysql -u root -p
GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' IDENTIFIED BY 'rootpwd'
MariaDb 10.0.10 is the minimum version required but more recent versions are preferred.
The Install procedure may differ depending on the Linux distribution you're using but most of the time it will consist in these commands (executed as root):

With Yum (Fedora, Cent OS, Red Hat):
yum update
yum install MariaDB-server or yum install mariadb-server
You will have to set the root password (i.e. rootpwd)

/usr/bin/mysql_secure_installation
Answer 'y' to all questions except "Disallow root login remotely?" where you need to answer 'n'

chkconfig mariadb on or chkconfig mysql on or systemctl enable mariadb
service mariadb start or service mysql start or systemctl start mariadb

With Apt-get (Debian, Ubuntu etc.):
apt-get update
apt-get install mariadb-server
You will have to set the root password (i.e. rootpwd)

/usr/bin/mysql_secure_installation
Answer 'y' to all questions except "Disallow root login remotely?" where you need to answer 'n'

chkconfig mysql on
service mysql start

If these commands fail to execute, ensure you have MariaDb to your source package list using apt-key and add-apt-repository (refer to the documentation of your version of MariaDb for more details).
To manually enable root access from remote machines:
mysql -u root -p
GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' IDENTIFIED BY 'rootpwd'
Oracle 11g is the minimum version required but more recent versions are preferred.

You can use an Oracle Database server to host XStudio's database.

Oracle Database / Oracle Database 11g is a commercial product.
Please contact Oracle if you wish to to purchase/install an Oracle Database edition.
On a Windows server, you can use MySql, MariaDb or SQL Server.

Starting from XStudio v1.2, MySQL 5.0.3 is the minimum version required but more recent versions are preferred.
  • Download the MySQL Database Server from http://dev.mysql.com/downloads/mysql or directly from our own repository MySql 5.6.25.0 for Windows 32bits/64bits

  • Execute the setup program (i.e. mysql-installer-community-5.6.25.0.msi)

    Choose the default options except when specified.

    mysql

    Select the most appropriate setup type (i.e. Server only)
    mysql

    mysql

    mysql

    mysql

    mysql

    mysql

    Select the most appropriate Config Type (i.e. Server Machine)
    mysql

    Provide the root paswword (i.e. rootpwd)
    mysql

    mysql

    mysql

    mysql

    mysql

    mysql

MariaDb 10.0.10 is the minimum version required but more recent versions are preferred.
SQL Server 2005 is the minimum version required but more recent versions are preferred.

You can use a Microsoft SQL Server Database server to host XStudio's database.

SQL Server is a commercial product.
Please contact Microsoft if you wish to to purchase/install an SQL Server.
Once you installed SQL Server, there is an important point to double-check: your server MUST have the TCP/IP protocol enabled:
sql server

IMPORTANT: With SQL Server, it is required to set the database server (or at least the database that is going to be created by the system) with a language that supports implicit date time format yyyy-mm-dd.
For instance you can set the default language as English or us-english.

Note that this will NOT prevent from storing accentuated characters in other language-sets (including asian's).

Install XStudio

This is where we are going to install XStudio application in Tomcat.


Please click on the appropriate option below:

  • Download the version of the XStudio Web Package you wish to install (from our download section)

    cd /var/lib/tomcat8/webapps
    mkdir xqual
    (only lowercase characters) cd xqual
    wget http://xstudio.alwaysdata.net/support/releases/<ver>/xstudio_v<ver>_web_package.zip
    (i.e. XStudio web package v12sp17)

  • Unzip the zip file

    unzip xstudio_v<version>_web_package.zip

  • Delete the zip file

    rm -f xstudio_v<version>_web_package.zip

  • In the end, you must have a structure similar to this one:


  • Download the version of the XStudio Web Package you wish to install (from our download section)

    Create a folder xqual in C:\Program Files\Apache Software Foundation\Apache 7.0\webapps (only lowercase characters)
    Download http://xstudio.alwaysdata.net/support/releases/<ver>/xstudio_v<ver>_web_package.zip and save it to C:\Program Files\Apache Software Foundation\Apache 7.0\webapps\xqual
    (i.e. XStudio web package v12sp17)

  • Unzip the zip file

  • Delete the zip file

  • In the end, you must have a structure similar to this one in C:\Program Files\Apache Software Foundation\Apache 7.0\webapps\xqual:

    install structure windows

Configure XStudio

Database

Upload the JDBC drivers


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

With MySql, you have nothing to do as the default JDBC drivers for MariaDb are 100% compatible with MySql.
With MariaDb, you have nothing to do as the JDBC drivers are pre-installed.
  • Download the JDBC driver for SQL Server from https://www.microsoft.com/en-US/download/details.aspx?id=11774 or directly from our own repository SQL Server JDBC driver 4.0 and 4.1

  • Unzip the zip file

  • Copy the full sqljdbc_3.0 folder in C:\Program Files\Apache Software Foundation\Tomcat 8.0\webapps\xqual\xstudio\jdbc\

    At the end, you should have this path available on the server:
    C:\Program Files\Apache Software Foundation\Tomcat 8.0\webapps\xqual\xstudio\jdbc\sqljdbc_3.0\enu\sqljdbc4.jar

Install SQLyog Community Edition

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.

    sqlyog sqlyog

    sqlyog sqlyog

    sqlyog sqlyog

    sqlyog

  • Execute SQLyog and connect to the remote Database Server:

    Click on the Create a new connection button
    sqlyog

    Provide a name for that connection
    sqlyog

    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
    sqlyog

    sqlyog

    You're now connected to your remote database server and you can manage it.


Create an empty database

  • Keep the SQLyog connection open

    Select the Database > Create Database menu item
    sqlyog

    Provide a name for the database: xstudio_db
    sqlyog

    You have now a new empty xstudio_db database
    sqlyog

    Open the User Manager
    sqlyog

    Create the user xstudio (ensure you have % selected in the Host combobox!)
    and provide a password for this user (i.e. xstudiopwd)
    sqlyog

    Open the User Manager
    sqlyog

    Grant all the rights to xstudio@% on the newly created xstudio_db database
    sqlyog

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.

XStudio will internally query the database only with this account.


Server Settings

Configure the JNLP access


Please click on the appropriate option below:

  • Edit the 3 following files:
    • /var/lib/tomcat8/webapps/xqual/xstudio/xstudio.jnlp
    • /var/lib/tomcat8/webapps/xqual/xstudio/xagent.jnlp
    • /var/lib/tomcat8/webapps/xqual/xstudio/xstudio.jsp
  • Set the codebase attribute (incl. protocol and port) of each of these files with the URL that points to where you unzipped the XStudio Web Package (i.e. http://<Tomcat server name or IP address>:8080/xqual).

For instance, the beginning of the xstudio.jnlp file should be similar to:

     
  • Edit the 3 following files:
    • C:\Program Files\Apache Software Foundation\Tomcat 8.0\webapps\xqual\xstudio\xstudio.jnlp
    • C:\Program Files\Apache Software Foundation\Tomcat 8.0\webapps\xqual\xstudio\xagent.jnlp
    • C:\Program Files\Apache Software Foundation\Tomcat 8.0\webapps\xqual\xstudio\xstudio.jsp
  • Set the codebase attribute (incl. protocol and port) of each of these files with the URL that points to where you unzipped the XStudio Web Package (i.e. http://<Tomcat server name or IP address>:8080/xqual).

For instance, the beginning of the xstudio.jnlp file should be similar to:


install server configuration

Generate the server settings

  • Start a web browser from any computer on the network, open the URL:
    http://<Tomcat server name or IP address>:8080/xqual/xstudio/ and click on the XStudio button

    install vm homepage

  • An error message appears complaining about the network settings

    fat client

    This is not surprising as we have not specified anywhere how to connect to the Database Server.

    Then, the Application Settings screen appears so that you can provide the database connection information

    Field Description
    Database server type This indicates which database server you're using:
    • MySql
    • MariaDB
    • Oracle
    • SQL Server
    driver jar path This indicates where XStudio 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 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 This indicates the IP address or the name of the database server.
    database name The name of the database (i.e. xstudio_db)
    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;
    username Username to connect to the database (i.e. xstudio)
    password Password corresponding to the user account (i.e. xstudiopwd)
    Max number of connections
    (default 64)    		 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 This indicates the bae URL pointing to the REST API (i.e. http://<Tomcat server name or IP address>:8080/xqual/api)
    REST API default username Default username to connect to the REST API. Each user can provide its own username/password in its user preferences though.
    REST API default password Default password to connect to the REST API. Each user can provide its own username/password in its user preferences though.

    You can leave all the other setting as-is for now.

    NOTE: you can also configure your server so that all the clients connect 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.

    You can find all the details about how to configure your system with ssh in the connecting through ssh section of the documentation.

  • Submit your changes (you will be asked where you want to save the configuration files)

    install server

    The 3 configuration files (xstudio.conf, requirement.conf, bugtracking.conf and sso.conf) are saved locally on the client.

    install server

Upload the server settings

  • Upload the 3 configuration files on the server so that they are applied.

    Please click on the appropriate option below:

    Upload xstudio.conf, requirement.conf, bugtracking.conf and sso.conf to /var/lib/tomcat8/webapps/xqual/xstudio/
    Upload xstudio.conf, requirement.conf, bugtracking.conf and sso.conf to C:\Program Files\Apache Software Foundation\Tomcat 8.0\webapps\xqual\xstudio\


    Configure the REST API server (mandatory step!)

    For the rest of the process, please click on the appropriate option below:

    • Copy the configuration files
      cp /var/lib/tomcat8/webapps/xqual/xstudio/*.conf /var/lib/tomcat8/webapps/xqual/

    • Copy the JDBC drivers
      cp -r /var/lib/tomcat8/webapps/xqual/xstudio/jdbc/*/*.jar /var/lib/tomcat8/webapps/xqual/WEB-INF/lib/

    • Restart Tomcat
      To ensure that the REST API server took into account the last changes properly, restart Tomcat.

      With Yum (Fedora, Cent OS, Red Hat):
      service tomcat restart

      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.

    • (Opt.) Only if your Linux distribution is a headless instance (with no GUI)
      The server will need a graphical resources to generate PDF report.
      On headless systems, such as production linux servers you will need to install a few libraries.

      On each system it can be pretty different but on a headless ubuntu servers for instance you will need
      to install those libs this way:

      apt-get install libxrender1
      apt-get install libfontconfig1
      apt-get install libxext6
      apt-get install libxmu6
      apt-get install libxmuu1
    • (Opt.) Only if your need to generate reports from XStudio.web that contain chinese, arabic or exotic character sets.
      The server will need additional fonts.
      On headless systems, such as production linux servers you will need to install those fonts.

      On each system it can be pretty different but on a headless ubuntu servers for instance you will need
      to install those fonts this way:

      apt-get install gsfonts gsfonts-other gsfonts-x11 ttf-mscorefonts-installer t1-xfree86-nonfree ttf-alee ttf-ancient-fonts ttf-arabeyes ttf-arphic-bkai00mp ttf-arphic-bsmi00lp ttf-arphic-gbsn00lp ttf-arphic-gkai00mp ttf-atarismall ttf-bpg-georgian-fonts ttf-dustin ttf-f500 ttf-sil-gentium ttf-georgewilliams ttf-isabella ttf-larabie-deco ttf-larabie-straight ttf-larabie-uncommon ttf-sjfonts ttf-staypuft ttf-summersby fonts-ubuntu-title ttf-xfree86-nonfree xfonts-intl-european xfonts-jmk xfonts-terminus
      For Chinese fonts you only need:
      apt-get install ttf-arphic-bkai00mp ttf-arphic-gbsn00lp ttf-arphic-gkai00mp

    • Ensure wkhtmltopdf file is executable
      chmod a+x /var/lib/tomcat8/webapps/xqual/wkhtml/linux32/bin/wkhtmltopdf

    • On specific OS you will also need to install libraries that are used by wkhtmltopdf (if you wish to generate PDF reports from XStudio.Web or the REST API)
      yum install -y glibc.i686
      yum install -y libXrender.i686
      yum install -y libfontconfig.so.1
      yum install -y libstdc++.so.6
      yum install -y libXtst.i686
      yum install -y zlib.i686
    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
    • Copy the configuration files
      Copy C:\Program Files (x86)\Apache Software Foundation\Tomcat 8.0\webapps\xqual\xstudio\*.conf
      to C:\Program Files (x86)\Apache Software Foundation\Tomcat 8.0\webapps\xqual\

    • Copy the JDBC drivers
      Copy the JDBC driver file (*.jar) from C:\Program Files (x86)\Apache Software Foundation\Tomcat 8.0\webapps\xqual\xstudio\jdbc\
      to C:\Program Files (x86)\Apache Software Foundation\Tomcat 8.0\webapps\xqual\WEB-INF\lib\

    • Restart the Apache Tomcat 8.0 Windows Service

    • Ensure wkhtmltopdf.exe file is executable
      C:\Program Files (x86)\Apache Software Foundation\Tomcat 8.0\webapps\xqual\wkhtml\win32_msvc\bin\wkhtmltopdf.exe

    Check the install

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

    Start XStudio from any computer

    • Open the URL: http://<Tomcat server name or IP address>:8080/xqual/xstudio/ and click on the XStudio button

      install vm homepage
    • Authenticate to XStudio using the default credentials:
      Username:admin
      Password:password

      fat client

    • A couple of warnings will popup to indicate that you're missing a license and that 2 major features that are enabled in the configuration have been automatically disabled:
      • The test case procedure Grid Editor
      • The ability to use rich-texts in the test case procedures

      fat client

      fat client

      It also summarizes the limitations of the community version:
      fat client

    • XStudio's GUI appears on the screen.

      fat client

    Start XStudio.web from any computer

    If you're installing a version < 10, you need FIRST to execute XStudio (the java client).
    • Open the URL: http://<Tomcat server name or IP address>:8080/xqual/xstudio.web/ and login

    • Authenticate to XStudio using the default credentials:

      Username:admin
      Password:password

      fat client

    • XStudio's GUI appears on the screen.

    Try the REST API

    You can access programmatically the XStudio 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":"XStudio","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 have XStudio Community Edition installed (with all its limitations).

    DON'T FORGET to ask for your FREE trial license!

    After you install your license key, all the limitations will be removed and all the additional features will be enabled automatically.