Meliora Testlab on-premise installation and upgrade guide

This document is a guide for installing and upgrading Meliora Testlab on your own premises.

Note, that installing Testlab on your own premises is an alternative for Meliora Testlab as a service. Using Testlab as a service enables you to avoid all hardware, installation, configuration, backup and maintenance related costs.

 

Introduction

This guide will walk you through the installation process to set up Meliora Testlab on a single server. The guide describes all requirements and needed assets for the installation, tells you how to set up your server for the installation, how to install the actual Testlab application, gives pointers on important files and directories related to the Testlab installation and helps you to plan on your server maintenance and security practices.

 

Testlab architecture

Meliora Testlab is a browser based client-server application. Users use the application with their browsers connected to a Testlab server. Testlab is fully browser based meaning that the typical use of Testlab requires no installations on client-side workstations.

Typical server side architecture of on-premises installed Testlab consists of

  • Oracle GlassFish Java EE application server, on top of
  • PostgreSQL relational database and local server file system for storage, on top of
  • Linux-kernel based operating system, on top of
  • Intel compatible x86 server hardware.

Support for more advanced configurations such as high-availability or proxied deployments are available from Meliora Ltd. 

 

Installation requirements

This chapter describes the software requirements and hardware recommendations for running Testlab. The installation package mentioned here means the installation package downloadable from www.melioratestlab.com for the installation.

 

Software requirements
  • Client browser
    • Chrome: Latest stable version
    • Safari: Latest stable version, supported on OS X only
    • Mozilla Firefox: Latest stable version
    • Internet Explorer: 10.0, 11.0
    • For all browsers: Minimum screen resolution of 1280 x 800 is recommended. JavaScript on browser must be enabled.
  • Java environment (server)
    • Oracle JDK 1.8 (formerly Sun JDK). Running the latest version of the JDK is highly recommended and running Testlab with OpenJDK is not supported.
    • Java environment must be installed with graphic capabilities supporting headless mode. For server environment, this usually means that the operating system must be installed with the needed X11 libraries to support this.
    • A JDK is required – Using only a JRE won’t work.
    • Note: Not included in the installation package.
  • Java Application server (server)
    • Oracle GlassFish 3.1.2.2
    • Note: Included in the installation package.
  • Operating system (server)
    • As Testlab is fully Java-based solution it should run on all operating systems supporting the Java environment and the application server described above. Testlab is known to run successfully on a number of Linux, Microsoft Windows and Mac OS X operating systems. For official cerfifications you can refer to Oracle’s System Requirements and Supported Platforms for GlassFish Server and the release notes of GlassFish 3.1.2.2 for more details.
    • Linux: Latest Debian stable (currently 7.x Wheezy) 64-bit amd64 and 32-bit i386 architectures are officially supported, meaning, that all Testlab releases are tested on this platform and the installation guide and setup process is supported to work on this operating system.
  • Database (server)
    • PostgreSQL 9.x with PostgreSQL JDBC driver.
    • Meliora Testlab is officially supported on latest PostgreSQL 9.6.x version but is implemented in a way that is version independent. Testlab is known to run successfully on multiple PostgreSQL versions from 9.0, 9.2, 9.3 and 9.4 branches.
    • Note: JDBC Driver is included in the installation package. 

The installation package downloadable from www.melioratestlab.com includes the needed installation packages for the GlassFish application server and the Testlab application (EAR).

 

Hardware recommendations

Testlab will run on all hardware compliant with the software requirements above.

During evaluation, Testlab will run well on any reasonably recent server or client workstation (eg. hardware acquired within the last three years) that is not constrained of resources. The hardware should have atleast 4GB of RAM which should be more than enough for running the OS, database system and the application server with 1GB of Java heap.

For production, Testlab runs well on

  • a modern server with multi-core CPU (any Intel Xeon based x86 server),
  • 4GB of RAM minimum, 8GB recommended,
  • file system with reasonably fast I/O (7200rpm hard disks in minimum).

Keep in mind, that server software is typically constrained by I/O and network performance and in addition, Testlab might run reasonably well on less memory but having enough memory for operating system and caching is always good for performance. Best performance for Testlab is with a system with high I/O capability and enough RAM.

For disk space the actual software components (excluding operating and database system) take few hundred megabytes. The real constraint comes from the file attachments added to Testlab. Testlab stores these files to the server’s file system so you must make sure the server has enough disk or storage space for these files. For example 20 gigabytes of free storage space after installation should hold a lot of files. Better yet, if you have a possibility to use logical volumes which can be enlarged on demand (for example storage space from a SAN) you can start small.

 

Server setup

Checklist Click to toggle

 

This chapter describes the preliminary setup and installations needed or recommended for the server where Testlab will be installed. If you have a server or a workstation with Java runtime installed and a PostgreSQL server available and you would like to evaluate Testlab with those you are free to skim through this chapter and skip directly to the Testlab installation. Keep in mind, that there are some optional dependencies which you might want to install but are not required (see below).

 

Operating system
  1. Install Debian Wheezy – a minimal server installation with only openssh-server is recommended.
  2. Make sure to update all repositories and install all available upgrades if any.
  3. Make sure to configure your server on your local time zone and ensure, that your server is configured to keep it’s time in sync (for example, install and configure ntp properly).
  4. Configure networking and we recommend you make sure your server is configured to have a real hostname instead of the one generated by the install.
  5. Set up the host name of your server correctly and in addition, make sure to add this hostname also to your /etc/hosts file. For example,
    # hostname
    myserver
    # cat /etc/hosts
    127.0.0.1      localhost myserver
    ...

    If this is not set up properly, GlassFish might fail to start by complaining about another process occuping the port 4848.

  6. As you are installing a server make sure the so called limits are configured properly. Especially number of open files should be configured to a large enough number to support running server software. As root, run
    # ulimit -n

    .. and verify, that “open files” / “nofile” is atleast 65536. For how to increase this limitation in Debian, please see the quick install guide below.

  7. Install a firewall to your operating system (such as ufw) but we recommend, that you install and setup your firewall after the Testlab setup is done and Testlab is verified to be working. This ofcourse only if your server is not connected to a public network during the installation.
  8. Install the needed X11 libraries to support Java graphics:
    # apt-get install libx11-6 libxext6 libxtst6 libxi6 xauth

 

Fronting Testlab with a Nginx reverse proxy

A recommended configuration for running Testlab is with a Nginx based reverse proxy. After you’ve successfully set up Testlab, please continue on with the guide here and install Nginx in front of your GlassFish installation.

 

.. Or alternatively, forwarding traffic from 80 or 443

For security reasons we highly recommend that the applications server is run with a non-privileged user account as instructed later in this guide. This means, that by default, the application server’s HTTP listener will listen for port 8080 and HTTPS listener will listen for port 8181. To configure application server to listen for default 80/443 ports would require the server to be run as a root which is not recommended.

For the users to be able to access Testlab from default 80 or 443 port you should use your operating system tools (typically iptables) to forward traffic from port 80 to 8080 and from port 443 to 8181.

 
PostgreSQL Database

If you already have PostgreSQL database setup or running at your local workstation so that it accepts network connections you are free to use it. Testlab is only a JDBC client from the database point of view and requires no special setup at PostgreSQL side.

Keep in mind that the actual database and the user for it are created later on as explained in Testlab installation chapter. 

For PostgreSQL on Debian you have two choices: Use the official postgresql.org-provided packages which provide you with the latest PostgreSQL 9.6 version we recommend, or install the version provided by the Debian’s own repositories (currently 9.1 in Wheezy).

 

Installing PostgreSQL 9.6 from postgresql.org repository

A guide for installing PostgreSQL from postgresql.org can be found here. To keep things short,

1. Register the repository to your Debian by creating a file /etc/apt/sources.list.d/pgdg.list with

deb http://apt.postgresql.org/pub/repos/apt/ wheezy-pgdg main

2. Import the repository key, update package lists and install the software by running

wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install postgresql-9.6 postgresql-client-9.6

This will install the database software and create the default database. Operating system user postgres can be used to access the database.

 

Or alternatively, install PostgreSQL 9.1 from Debian repository

A guide for installing PostgreSQL for Debian can be found here. To keep things short, run

# apt-get install postgresql postgresql-client

This will install the database software and create the default database. Operating system user postgres can be used to access the database.

 

PostgreSQL security

By default, the installation configures the database security (in pg_hba.conf file) so that the default database can only be accessed locally with “peer” method. This means, that on access, PostgreSQL obtains the operating system user name and tries to match it to the database user name – it it matches access is granted. This method also allows only local connections so no TCP/IP based network connections are allowed for postgres user by default. This basicly means that by default, the database is only accessible by root user by changing to the user postgres and running PostgreSQL tools locally (for example, psql).

 

Configuring PostgreSQL

You should configure your installed PostgreSQL to allow remote network connections. Edit the /etc/postgresql/9.3/main/postgresql.conf file with

#------------------------------------------------------------------------------
# CONNECTIONS AND AUTHENTICATION
#------------------------------------------------------------------------------

# - Connection Settings -

listen_addresses = 'localhost, your required, ip-numbers, here'

The list of addresses here are the addresses the PostgreSQL listens for network connections. If you are running Testlab on the same server localhost is sufficient, but make sure that this contains the needed addresses relevant to your setup. 

For evaluation the above is enough. For production use we recommend that you configure and tune your server with best practices described here and especially make sure your server is configured with autovacuum on.

When making changes to the configuration make sure to restart PostgreSQL for changes to take effect by running

# /etc/init.d/postgresql restart

 

Java runtime

Server should have 1.8 Oracle’s JDK installed. Go to Oracle’s download page and download the latest Java SE 8 JDK. Make sure to download the .tar.gz package instead of .rpm if installing on Debian.

To install Java runtime under /opt in Debian, download the installation package to the /opt directory and run

# cd /opt
# tar xfz jdk-8u121-linux-x64.tar.gz
# rm -f jdk-8u121-linux-x64.tar.gz

Append the directory of your installed JRE to your global server PATH so that the binaries are always found by default by editing /etc/profile file and appending

export JAVA_HOME=/opt/jdk1.8.0_121
export PATH=$JAVA_HOME/bin:$PATH

Verify, that the JRE is installed correctly by opening a new server session (for the profile file to take effect) and running java -version which should print out the version number of the installed Java runtime.

 

Optional dependencies

For drawing the requirement diagrams Testlab uses a library which relies on a graph visualization software called Graphviz. To install Graphviz on Debian, run

# apt-get install graphviz

Note: Installing Graphviz is optional. If it is not installed the Relation diagram and Traceability diagram in Reports-menu won’t be accessible.

 

Creating an user

For security reasons, you should create a technical user on your server to run Testlab. This user will be used to run the GlassFish application server and all the binaries will be installed to the home directory of this user.

Add a new user to your server and make sure that the home directory of the user holds enough disk space for the installation. Also keep in mind, that this user must have access to read and write to the directory which will hold the file attachments of Testlab.

For the rest of the document we will assume that the name of the created user is testlab and the home directory of this user is /home/testlab.

 

Testlab installation

In this chapter we describe the steps to install and setup of Meliora Testlab on a server which all the necessary configuration is done, PostgreSQL database server and a database is available and all needed server dependencies are installed on. The installation package of Testlab comes pre-bundled with a Bash based installation script for Linux servers.

Note: As a fully Java platform based application Testlab is also runnable on Microsoft Windows servers. At the time being, no automatic installation script is provided for Windows and the application server configuration must be done manually. The Linux installation script is well documented and a server administrator with well enough knowledge on Oracle GlassFish is able to run the needed asadmin commands or configure the settings manually from the GlassFish DAS if a Windows Server installation is preferred.

 

Create database for Testlab
Checklist Click to toggle

 

To create user and a new database to PostgreSQL, run

# su - postgres
# createuser -P -d -R -S testlab
Enter password for new role: testlab
Enter it again: testlab
# createdb --owner=testlab testlab
# psql -c "alter schema public owner to testlab" testlab

You can enter a password of your liking but keep in mind, that you must edit the install script later on for the install to match the database password you entered.

Note: The user must have database creation rights (-d) for the install to be able to create and re-create the testlab database if needed. Also, the user must own the schema in the database.

 

Install and configure GlassFish application server
Checklist Click to toggle

 

Meliora Testlab runs on Oracle’s GlassFish application server. A Bash based installation script for Linux is provided in the installation package which provides the easiest way to setup the application server environment.

To setup the application server, 

1. Extract the Testlab on-premise installation package to the home directory of the user created for running Testlab.

# su - testlab
# cd /home/testlab
# unzip meliora-testlab-install.zip

2. Copy the license key file testlab_license.key to the same directory. You get the license key file via e-mail when you download the on-premise installation package from www.melioratestlab.com.

3. The name of the installation script is install_evaluation_glassfish.sh. Make sure the database and SMTP server settings defined at the start of this script are correct. 

# database settings
DB_HOST=localhost
DB_PORT=5432
DB_NAME=testlab
DB_USER=testlab
DB_PASSWORD=testlab
# e-mail settings for sending e-mail
SMTP_HOST=localhost
SMTP_PORT=25
SMTP_FROM=testlab@localhost

The DB_ parameters are used to setup the database connection pools and SMTP_ parameters are used to setup the SMTP server for sending e-mails from Testlab. Make the needed changes if needed and continue on.

4. Run the installation script as testlab user. The script must be given the name of the Testlab EAR file to deploy as a sole argument. The EAR file is found in the installation package and was extracted to the home directory.

# cd /home/testlab
# ./install_evaluation_glassfish.sh ear-[VERSION].ear

Note! Make sure you copied the license key file (as explained in step 2.) to the installation directory as the existence of this file is mandatory for running the installation script.

Note! If you encounter errors relating to port 4848 such as “There is a process already using the admin port 4848 — it probably is another instance of a GlassFish server.” make sure that

  1. There is no process reserving the needed ports (4848 in this case) – and ofcourse, GlassFish is not running for some reason.
  2. The host name resolves and is pingable from the server itself. This means, that if the hostname of your server is “myserver”, make sure to add the matching name to your /etc/hosts file for 127.0.0.1. 

When asked for the password of the GlassFish admin user for the first time enter a blank. This is because the current admin password is empty and is to be changed. When asked for the password again enter a password you wish to set for the GlassFish admin account.

This script

  • deletes the existing GlassFish installation from ./glassfish3 directory if any,
  • extracts the GlassFish application server to the ./glassfish3 directory,
  • copies the needed dependency libraries to GlassFish domain’s lib/ directory,
  • replaces the default docroot index.html page with a page redirecting to Testlab,
  • sets up file permissions by removing other and group access to application server files,
  • starts the GlassFish server for configuration and configures
    • JVM options,
    • HTTP listener options,
    • database connection pools and data sources,
    • SMTP server mail session for sending e-mail and
  • changes the password of GlassFish’s admin user,
  • enables GlassFish secure admin mode which allows remote access to the DAS (at port 4848),
  • restarts GlassFish,
  • copies Testlab’s evaluation license key file to place and
  • deploys the Testlab application to GlassFish.

After running the script, the application server is configured to run Testlab and the application is deployed. Note, that during the script execution you will be asked for the GlassFish admin account password for executing the needed asadmin commands.

 

I happen to have Java older than 1.8 and need to run GlassFish

Running GlassFish with Java 1.8 will fail with some OSGI container related exceptions. To run with Java 1.8, you need to edit the osgi.properties file found in domains/domain1/config/ or config/ directory under your GlassFish installation. Add this line to end of this file and try again:

jre-1.8=${jre-1.7}

The installer script provided does this automatically and the install should work as it is with JDK 8.

 

Something went wrong – I want to run the installer again

If you want to run the installer script again, make sure that GlassFish is not running. When you run the installer script, it deletes the existing GlassFish install directory (glassfish3/) but it does not detect if you have a running process on your server.

Before running the installer, check if you have a server running with

# ps ax | grep glassfish

If this command prints out a process running GlassFish, for example like

22373 pts/0    Sl     2:13 /opt/jdk1.8.0_121/bin/java -cp /home/testlab/glassfish3/glassfish/modules/glassfish.jar ...

.. please make sure to kill this process. To make sure the process is not running stop it by running

# kill -9 22373

After this, you are free to run the installer script again.

 

Increasing reserved memory

By default, running the installation script will create the GlassFish domain configuration with JVM options which reserves 1GB (1024MB) of RAM for the server. This is enough for evaluation, but for a good performing production deployment we recommend that the heap size is increased to 2GB.

To increase the heap from 1GB to 2GB make sure the application server is running and execute

# ./asadmin delete-jvm-options '-Xmx1024m'
# ./asadmin create-jvm-options '-Xmx2048m'

The heap size can also be increased by editing the matching options from DAS console’s view Configurations / server-config / JVM Settings / JVM Options.

Note: Make sure that your server has enough RAM for the heap, operating system and other software components so it won’t get constrained and start swapping heavily.

 

Run Meliora Testlab setup
Checklist Click to toggle

 

Testlab provides a browser based setup wizard which allows you to

  • initialize the database tables of Testlab and insert the base data including the administrator user account to the database and
  • write the local configuration file with the needed settings.

To run Testlab setup access /testlab/setup/ with your browser (http://yourserver:8080/testlab/setup/ on a fresh GlassFish installation). Running the wizard requires the details below.

  • Company information
    • Company name *: Name of your company. When Testlab is possibly licensed the license key will be granted for this company.
    • From E-mail address *: E-mail address to use as a sender for Testlab sent e-mails. 
      Note: Please enter a valid e-mail address which has access to send e-mails in your organization. Entering a non-valid address here will probably result in Testlab sent e-mails ending up undelivered or blocked as spam.
  • Administrative user
    • Full name *: Full name for the administrative company administrator account
    • E-mail *: E-mail address of the company administrator
    • User ID *: An user id for the company administrator. This user id will be used when logging on to Testlab with this account.
    • Password *: Password for the company administrator account
    • Confirm password *: Enter the above password again
  • Server information
    • Host name *: Host name of the Testlab server.
    • Host domain: Host domain of the Testlab server.
      Host name and domain are used to construct the end user addresses for accessing Testlab and must be set to the values matching the host Testlab is accessed from. For example, if you are setting up Testlab to be accessed from http://testlab.mycompany.com you should set host name as “testlab” and host domain as “.mycompany.com“. Values must match to the URL address end users will use to access Testlab.
    • Use HTTPS *: Check this option if you prefer to use HTTPS instead of HTTP
    • HTTP port *: HTTPS port of the server – defaults to 8080 which is the default HTTP port of GlassFish.
    • HTTPS port *: HTTPS port of the server – defaults to 8181 which is the default HTTPS port of GlassFish.
      Port options should be set to values matching the host Testlab is accessed from. For example, if you are redirecting traffic from port 80 to 8080 (or from port 443 to port 8181 and using SSL) for Testlab to be accessed from http://testlab.mycompany.com the HTTP port value should be set to 80. Values must match to the URL address end users will use to access Testlab.
    • File attachment directory *: Directory on server’s file system to use for storing Testlab’s attached files. Please use an absolute path and make sure the user running the application server has access to read and write to this directory.
  • Submit
    • (Re-)create database: Check this option to create and initialize the database. Leave it unchecked if you just prefer to setup your local configuration file and leave the already created database intact.

Press the Run setup! button to run the setup. After the setup a dialog will open up indicating if the run was successful. The dialog contains a setup log from the server which tells you if anything was in error. The file is also written to the server’s GLASSFISH_HOME/glassfish/domains/domain1/config directory for later access.

After setup you should be able to access Testlab from the http(s):///testlab with the company administrator account created during the setup.

 

Enabling setup if already run

When a setup is run access to the setup wizard is locked. If you wish to run the setup wizard again for an already setup Testlab you must re-enable the setup wizard by editing your local configuration file. Edit your local GLASSFISH_HOME/glassfish/domaings/domain1/lib/classes/testlab.properties configuration file with

setup.disabled=false

and restart GlassFish to access the setup wizard.

 

Important files and directories

This chapter lists and describes the relevant files and directories for Testlab installation and maintenance. The shortcuts referred below are

  • GLASSFISH_HOME: The installation directory of the application server – glassfish3/ if the server is installed with the provided installation script.
  • DOMAIN_HOME: The directory of the GlassFish domain Testlab is running with – GLASSFISH_HOME/domains/domain1/ if the server is installed with the provided installation script.

Relevant files and directories for an on-premise Testlab installation are:

  • GLASSFISH_HOME/bin/asadmin
    An executable to run commands on GlassFish domain 
  • DOMAIN_HOME/lib/classes/testlab.properties
    A local Testlab configuration file. Changes to this file take effect by restarting the server.
  • DOMAIN_HOME/lib/classes/testlab_license.key
    Testlab license key file
  • DOMAIN_HOME/logs/
    Logging directory which holds the
    • server.log
      GlassFish application server domain log file. All logging done by the application server itself is written to this file.
    • testlab.log
      Testlab’s main log file.
    • testlab_api.log
      A log file for Testlab’s API related functions.
    • testlab_comet.log
      A log file for Testlab’s browser push technology related functions.
    • testlab_errorreports.log
      A log file for reports from unexpected Testlab errors.
    • testlab_event.log
      A log file for Testlab’s event sub system.
    • testlab_import.log
      A log file for Testlab’s import related functions.
    • testlab_report.log
      A log file for Testlab’s report sub system.
  • DOMAIN_HOME/config/domain.xml
    • A main configuration for application server domain. It is not adviced for this file to be edited by hand but via DAS (Domain Administration Server) console accessible by default from :4848 port.

 

Maintenance and backups

 
Starting and stopping the server

Change to GLASSFISH_HOME/bin and run

# ./asadmin start-domain domain1

to start the server and

# ./asadmin stop-domain domain1

to stop the server.

 

Managing the domain

You can manage the GlassFish application server domain with the asadmin command and/or accessing the DAS console. DAS console is by default accessible from server’s port 4848.

 

Backups

To backup a Testlab installation the following artifacts should be backed up:

  • Testlab’s PostgreSQL database,
  • attached files in the server file system,
  • GLASSFISH_HOME directory on the server.

We highly recommend backing up your whole server for easy restoration of a running system if possible.

 

Security considerations

This chapter gives pointers on security best practices and information how to setup your server environment in a secure way. You should not consider this chapter as a definite guide on how to secure your server. Securing a server in your organization is always on your own responsibility. 

 

Deploy a firewall

The server should always be protected by a firewall restricting atleast incoming traffic. Deploy a firewall of your choice and open up only needed ports to the server services. As Testlab is a browser based application you should only open up HTTP and/or HTTPS listener ports to the server.

 

Run services with non-privileged users

Install the services so that they run on non-privileged users as instructed in this guide. Services such as the application server should never be run as a privileged user such as root. Make sure, that the file permissions for these users are correctly set up and for example, application server logs are not world readable. 

 

Restrict DAS access

Never allow outside access to DAS console in port 4848. We recommend blocking outside access to port 4848 and accessing the console when needed with SSH.

 

Harden server with best practices

You should make sure your server, server software including PostgreSQL and GlassFish are hardened with security best practices in mind.

 

Setting up SSL

It is recommended to set up your application server to use SSL encryption with a valid certificate. This ensures transport confidentiality between your Testlab server and your client browsers. A quick how-to guide to setting up SSL follows.

Note: For production installations, we recommend that you set up a Nginx based reverse proxy on your server to terminate SSL. For instructions on how to do this, see the documentation.

Step 1. Install Unlimited Strength Java Cryptography Extension (JCE)

By default, JDK ships with limited strength cryptography extensions. To enable stronger SSL ciphers Unlimited Strength JCE files must be installed. Go to Oracle’s download page and download “Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files” that match your JDK version.

Extract the archive (for example UnlimitedJCEPolicyJDK7.zip) and copy the extracted .jar files to jre/lib/security folder under your JDK installation.

Step 2. Change GlassFish master (keystore) password

It is recommended to change the keystore password for your domain to protect the keys and certificates. The default password is changeit and you can change it by running the command below.

# cd GLASSFISH_HOME/bin
# ./asadmin change-master-password domain1
Please enter the master password> changeit
Please enter the new master password> mynew5trongpassword
Please enter the new master password again> mynew5trongpassword
Command change-master-password executed successfully.

Step 3. Generate certificate request

To request a certificate from an authority of your choice you need a certificate request file. A new key and a CSR file for it valid for a year can be generated with following commands:

# cd GLASSFISH_HOME/domains/domain1/config
# keytool -genkey -keysize 2048 -validity 365 -alias mytestlab.mydomain.com -keyalg RSA -keystore keystore.jks
Enter keystore password: mynew5trongpassword
What is your first and last name?
[Unknown]: mytestlab.mydomain.com
What is the name of your organizational unit?
[Unknown]: Testing Dept
What is the name of your organization ?
[Unknown]: My Company Ltd
What is the name of your City or Locality ?
[Unknown]: London
What is the name of your State or Province ?
[Unknown]:
What is the two-letter country code for this unit ?
[Unknown]: UK
Is CN=mytestlab.mydomain.com, OU=Testing Dept, O=My Company Ltd, L=London, ST=, C=UK correct?
[no]: yes
Enter key password for
(RETURN if same as keystore password):
# keytool -certreq -alias mytestlab.mydomain.com -keystore keystore.jks -file mytestlab.mydomain.com.csr
Enter keystore password: mynew5trongpassword
#

Note: Replace the hostname, domain and other information to match your organization you are requesting the certificate for. The certificate request is written to file mytestlab.mydomain.com.csr.

Step 4. Get certificate from an authority

Use the SSL authority of your choice and get an validated certificate by delivering the certificate request file (or the information contained in the file) to the authority. You should get back a signed certificate file from the authority and optionally all the intermediate certificates needed if any.

Intermediate certificates are the certificates that fulfill the certificate chain for the authority in question. For the browser to be able to validate your certificate correct it must have a full verified chain of certificates from your server’s certificate through to some root certificate in the client browser. For this, it is common that some intermediate certificates might be needed.

Step 5. Import certificates to GlassFish’s keystore

Let’s presume you got a certificate file mytestlab.mydomain.com.crt and intermediate certificate myauthority.crt back from your authority. To import these certificates to keystore run the following commands.

# cd GLASSFISH_HOME/domains/domain1/config
# keytool -import -trustcacerts -alias root -file myauthority.crt -keystore keystore.jks
...
# keytool -import -trustcacerts -alias mytestlab.mydomain.com -file mytestlab.mydomain.com.crt -keystore keystore.jks
...

Step 6. Configure GlassFish to use the provided certificate

For GlassFish to use your imported certificate in it’s http(s) listener you must configure the matching http-listener for it. You can adapt and run the following commands or, manually configure the “Certificate NickName” from Configurations > server-config > Network Config > Network Listeners > http-listener-2 > SSL to match the alias you gave for your certificate in the commands above.

# cd GLASSFISH_HOME/bin
# ./asadmin set server.network-config.protocols.protocol.http-listener-2.ssl.cert-nickname=mytestlab.mydomain.com

Note: You must have your domain running for asadmin set commands to work.

If you don’t want to allow non-SSL HTTP traffic to your GlassFish you can disable the HTTP listener http-listener-1.

# cd GLASSFISH_HOME/bin
# ./asadmin set server.network-config.network-listeners.network-listener.http-listener-1.enabled=false

Step 7. Disable weak ciphers and SSL v3

To make sure GlassFish uses strong ciphers for your connections you should go to Configurations > server-config > HTTP Service > Http Listeners > http-listener-2 > SSL, disable SSL3 and pick only strong cipher suites to be enabled. As a rule of thumb, you should make sure to disable DES and RC4 based ciphers and prefer modern ciphers such as AES and prefer modern protocols such as TLS over SSL. All suites below 128 bit in strength must be disabled.

We highly recommend that you analyze and verify your configuration with a verification tool such as testssl.sh

Step 8. Restart GlassFish and verify certificate

Restart your GlassFish and open up Testlab from SSL protected port. From your browser, validate that the certificate returned is valid and the information match to the certificate your originally requested.

Step 9. Setup Testlab for SSL use

For Testlab to prefer SSL connections you must tell Testlab to prefer SSL connections. If you haven’t run the Testlab setup wizard yet, make sure to check the option to use HTTPS and specify the right HTTPS port to the wizard for the configuration to be set up correctly.

If you already run the wizard, you can re-run it and leave the (Re-)create database selection unchecked. This way the testlab.properties configuration file will be overwritten with new settings.

If you for some reason not prefer to run the set up wizard again you can edit the testlab.properties configuration file by hand and enable SSL. To enable SSL edit configuration as follows:

...
server.scheme=https 
...
server.port.https=
...

Note: Make sure to restart GlassFish for the change to take effect.

 

Testlab licensing

Running on-premise Testlab requires a valid license. When you download the installation package it always comes pre-bundled with a 14 day evaluation license key file for evaluating Testlab. A production license is always granted for a single company and tied to a host name of the server running the Testlab.

If a valid license is missing Testlab does not start and you should encounter license related errors in your Testlab and/or application server log files indicating the license key is missing or not valid.

 
Upgrading a license

When you upgrade your Testlab license and are provided with a new license key file, you should install the license key file by copying the file to the DOMAIN_HOME/lib/classes/testlab_license.key and restarting the GlassFish domain. You can verify that the license key takes effect from testlab.log when the server starts up.  

 

My evaluation key has been expired

Please contact us and we get this sorted out.

 

Quick install

“All this is good and dandy but I just want to get it running and check it out.”

In this chapter we give you a quick how-to type guide on how to setup a virtual machine on your workstation and install Testlab for testing. Keep in mind, that you should read through the guide above to get to know your local installation. And, that this guide won’t probably be good enough for production use especially from security stand point. For this quick install how-to to work you need network access as we will be installing the netinst-variant of Debian.

 

Creating the virtual machine

For this quick install we’ll be using VirtualBox. If you prefer to use some other x86 compatible virtualization platfrom feel free.

1. Download and install VirtualBox if you don’t already have it. Start VirtualBox Manager.

2. Click New and create a new virtual machine:

  • Name: Testlab
  • Type: Linux
  • Version: Debian (64-bit)
  • Memory size: 2048MB
  • Create a virtual hard drive now: yes
  • Hard drive file type: VDI
  • Storage on physical hard drive: Dynamically allocated
  • File location and size: Choose a location for your hard disk image, select 8GB for size. Note that the install reserves the disk space dynamically meaning, that the 8GB won’t be reserved as it is from your local workstation hard drive. It is ofcourse recommended to have this disk space in reserve for to make sure you don’t run out of disk space on your machine.

 

Installing Debian

1. Download Debian 7.x Wheezy network install image amd64 (direct link to the image at the time of writing). If the direct link has been expired, please go to the download page and fetch Wheezy network install image amd64.

2. Attach the downloaded image to the Testlab virtual machine’s optical drive. Click Settings and configure “Testlab” virtual machine with

  • Storage / Controller: IDE – Empty / Click the optical media icon and “Choose a virtual CD/DVD disk file…”
  • Choose the debian-7.x.x-amd64-netinst.iso disk image file, click OK

3. Start the virtual machine and select “Install” from “Debian GNU/Linux installer boot menu”

4. Select your language, your location, your locale and your keymap to use. Make sure to select a .UTF8-ending default locale such as “en_US.UTF-8”.

5. Enter “testlab” as Hostname. Leave Domain name blank.

6. Enter a root password, twice, and make sure to remember this.

7. Create an user account for your machine by giving a full name, account user name and a password.

8. Partition your machine by selecting “Guided – use entire disk”, select disk (sda), “All files in one partition” and “Finish partitioning and write changes to disk”. Confirm to write changes to disk.

Note: As we are setting up a virtual machine this has nothing to do with your workstation’s disk ofcourse. You are partitioning the hard drive of the virtual machine.

9. Wait for the installer to install the base system. When the installer asks for a mirror repository select one close to your location.

10. Enter HTTP proxy information if needed – if you have a direct connection to network you can leave this blank.

11. Wait for Debian to continue install. Answer to “Participate in the package usage survey ?”.

12. When asked for software selection select only

  • SSH server and
  • Standard system utilities

13. Install the GRUB boot loader to master boot record?

14. Installation finishes. Click continue. Your virtual machine will now reboot and you should get a prompt for “testlab login:”.

Congratulations. You now have a Debian base system running to install Testlab.

 

Configure virtual machine networking

By default, VirtualBox virtual machines are set up with NAT networking. This means, that the virtual machine itself has access to external network through your workstation (i.e. internet) but for you to have access to the virtual machine you need to set up so called port forwarding. If you are using a virtual machines in bridged mode or in some other networking configuration which allows you to access the virtual machine directly you can skip this part.

If you wish to configure bridged networking or any other suitable network configuration to suit or internal network you can refer to the VirtualBox manual.

1. Select Testlab virtual machine and click Settings

2. Configure Network / Adapter 1 / Port Forwarding and add

  • Rule 1, TCP, Host IP: blank, Host Port: 2222, Guest IP: blank, Guest Port: 22
  • Rule 2, TCP, Host IP: blank, Host Port: 18080, Guest IP: blank, Guest Port: 8080
  • Rule 3: TCP, Host IP: blank, Host Port: 14848, Guest IP: blank, Guest Port: 4848 

What this does is to configure ports from your workstation (Host) to be forwarded to Testlab virtual machine’s ports. For example, you can open up a SSH connection to localhost:2222 on your workstation which in reality opens up the connection to the virtual machine’s SSH server (at port 22). The rest of the ports are

  • 18080 -> 8080: GlassFish HTTP listener
  • 14848 -> 4848: GlassFish Admin console listener 

As a note, we forward 18080 instead of 8080 to make sure the ports on your local workstation are not reserved. If you have some other web server such as Tomcat running locally it will be in conflict with the port 8080 so we forward 18080 for simplicity’s sake in this how-to. This means ofcourse that you must have these 2222, 18080 and 14848 ports free on your local workstation. If not so, feel free to change the ports to some other value but keep in mind, that for the rest of this how-to you should also replace the matching ports to your changed values.

 

Add virtual machine host to your hosts-file

As we will be accessing the virtual machine through forwarded ports you should add an alias for your local workstation localhost to point to the host name of your virtual machine. Open up hosts-file on your local workstation (for example /etc/hosts or system32/drivers/etc/hosts in Windows) and add a “testlab” alias to your 127.0.0.1 host. 

127.0.0.1    localhost testlab

After this, you should be able to access your forwarded virtual machine ports (see above) from testlab:2222, testlab:18080 and testlab:14848.

 

Setup OS and install dependencies

1. Open up SSH connection to testlab:2222 and login as root to make sure port forwarding works as expected

# ssh -p 2222 root@testlab
...
root@testlab:~#

You can also do the configuration directly in VirtualBox console window but using your local SSH terminal is often more comfortable.

2. Setup limits.conf

# nano /etc/security/limits.conf

… add

*                soft     nofile          65536
*                hard     nofile          65536
root soft nofile 65536
root hard nofile 65536
# nano /etc/pam.d/common-session

… add

session required pam_limits.so
# nano /etc/pam.d/common-session-noninteractive

… add

session required pam_limits.so

3. Setup locales (en_US.UTF-8 below, replace with the locale you selected earlier)

# dpkg-reconfigure locales

Make sure your locale is selected and select . Select the locale as default locale for the system environment.

# nano /etc/default/locale

… add

LC_ALL=en_US.UTF-8

4. Reboot machine. After reboot login as root again.

# shutdown -r now

5. Install PostgreSQL and other dependencies

# apt-get install libx11-6 libxext6 libxtst6 libxi6 xauth postgresql postgresql-client graphviz unzip

6. Install Java runtime

Download the latest Java SE 8 JDK .tar.gz-package for Linux x64 architecture. If the link does not work go to Oracle’s Java download page and select Java SE 8 JDK download link. Transfer the downloaded file to virtual machine’s /opt directory.

myworkstation# scp -P 2222 jdk-8u121-linux-x64.gz root@testlab:/opt/

And as a root on virtual machine

# cd /opt
# tar xfz jdk-8u121-linux-x64.gz
# rm jdk-8u121-linux-x64.gz
# nano /etc/profile

… add

export JAVA_HOME=/opt/jdk1.8.0_121
export PATH=$JAVA_HOME/bin:$PATH

Logout and relogin as root and verify, that the Java runtime is installed correctly.

# exit

… and relogin as root and run

# java -version
java version "1.8.0_121"
Java(TM) SE Runtime Environment (build 1.8.0_121-xxx)
Java HotSpot(TM) 64-Bit Server VM (build xx.xx-xxx, mixed mode)

7. Create an user for running Testlab

# adduser testlab

… and lock the user so it is only accessible by running “su – testlab” as root on the server.

# usermod -L testlab

 

Database creation

To create user and a new database to PostgreSQL, run

# su - postgres
# createuser -P -d -R -S testlab
Enter password for new role: testlab
Enter it again: testlab
# createdb --owner=testlab testlab
#
psql -c "alter schema public owner to testlab" testlab

You can enter a password of your liking but keep in mind, that you must edit the install script later on for the install to match the database password you entered.

Note: The user must have database creation rights (-d) for the install to be able to create and re-create the testlab database if needed. Also, the user must own the schema in the database.

 

GlassFish and Testlab application installation

All tasks here should be run as a testlab user by running “su – testlab” as a root.

1. Download Testlab onpremise installation package and as a testlab user, extract it to testlab user’s home directory

# su - testlab
# cd /home/testlab
# unzip meliora-testlab-install.zip

2. Copy the testlab_license.key license file you got in the e-mail you received when downloading Testlab to the same directory as above.

3. Run installer script to setup GlassFish to /home/testlab/glassfish3 and deploy the Testlab application from the provided EAR package

# ./install_evaluation_glassfish.sh EAR_FILE_NAME

Replace EAR_FILE_NAME with the name of the .ear file extracted from the installation package.

Make sure that the application server is not already running when executing this script. This script will change the password of your GlassFish admin account: first, when asked for a password enter a blank as the current admin password is empty and secondly, enter the password for you GlassFish admin account twice to change it.

Note: If you are targeting a different PostgreSQL server than the one suggested in this quick install guide you must edit the script to enter the target database details. In addition, this script will configure the SMTP server for sending the e-mails from Testlab to localhost. If you prefer to use some other SMTP server for sending e-mail, edit the script and enter the needed details.

4. Open up http://testlab:18080/testlab/setup to your browser. Run Meliora Testlab setup by entering

  • Company information
    • Company name *: My Company Ltd
    • From E-mail address *: a_valid_sender@yourdomain.com
  • Administrative user
    • Full name *: Your name
    • E-mail *: Your e-mail address
    • User ID *: A preferred user id for your soon to be created Testlab user account
    • Password *: Password for your soon to be created Testlab user account
    • Confirm password *: Enter the above password again
  • Server information
    • Host name *: testlab
    • Host domain: Leave as blank
    • Use HTTPS *: no
    • HTTP port *: 18080
    • HTTPS port *: 8181
    • File attachment directory *: /home/testlab/attachments
  • Submit
    • (Re-)create database: yes

Press “Run setup!” and confirm the setup. Wait a while and a green dialog with an install log should open up indicating a successful setup.

 

All done!

You can now log on to your Testlab by opening http://testlab:18080/testlab with your browser and entering the credentials you ran the Testlab setup with. We recommend that you log on to the Demo project and familiarize yourself with Testlab’s help manual found in the Help-menu.

 

Upgrading Meliora Testlab

Upgrading a Meliora Testlab installation is a procedure consisting of

  1. backing up your existing database content,
  2. executing one or more SQL scripts to the Testlab database and
  3. deploying a new version of the Testlab’s EAR package.

Testlab is always upgraded one version forward at the time meaning, the database scripts of each version must be committed one at the time at the right ascending versioning order. The EAR packages does not have to be deployed separately for each version. We highly recommend keeping your Testlab up to date to ease up the upgrade process.

 

 



 
 
Best-of-class cross-browser hosted SaaS quality and test management, testing and issue management tools to improve your quality. Site information.