Guides 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.
Heads up! This documentation is for specific Debian, Java & PostgreSQL version. The guide should be easily adapted to be used for newer versions. For Java & PostgreSQL, we always recommend that you use the latest stable versions available and for Operating System, you should install a version with sufficient support for (security) updates.
-
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.
A typical server-side architecture of on-premises installed Testlab consists of
- Payara Java EE application server (formerly Oracle Glassfish), 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 is 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 that can be downloaded from www.melioratestlab.com for the installation.
Software requirements
- Client browser
- Chrome: a Latest stable version
- Safari: The latest stable version, supported on OS X only
- Mozilla Firefox: a Latest stable version
- Internet Explorer: Edge
- For all browsers: A minimum screen resolution of 1280 x 1024 is recommended. JavaScript on the browser must be enabled.
- Java environment (server)
- Azul Zulu for Java version 8 (https://www.azul.com/downloads/zulu/zulu-linux/)
- Java environment must be installed with graphics capabilities supporting headless mode. For a 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)
- Payara Server (Full)
- Note: Included in the installation package.
- Operating system (server)
- As Testlab is a 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 Linux, Microsoft Windows, and Mac OS X operating systems. For official certifications, you can refer to the documentation of the Payara Server for more details.
- Linux: The latest Debian stable 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 are supported to work on this operating system. Note: This guide might refer to a specific Debian release in some commands (such as “bullseye”). You recommend that you always install the latest release of Debian and adjust the commands accordingly.
- Database (server)
- PostgreSQL 13.x+ with PostgreSQL JDBC driver.
- Note: JDBC Driver is included in the installation package.
The installation package downloadable from www.melioratestlab.com includes the needed installation packages for the Payara application server and the Testlab application (EAR).
Hardware recommendations
Testlab will run on all hardware compliant with the software requirements above.
During an 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 by resources. The hardware should have at least 4GB of RAM which should be more than enough for running the OS, database system, and the application server with 2GB of Java heap.
For production, Testlab runs well on
- a modern server with a multi-core CPU (for example any Intel Xeon-based x86 server),
- 8GB of RAM minimum, 8GB recommended,
- a file system with reasonably fast I/O (solid-state storage preferred).
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 the operating system and caching is always good for performance. The 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 a 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 can use logical volumes that can be enlarged on demand (for example storage space from a SAN) you can start small.
- Client browser
-
Server setup
To continue with this chapter, make sure you have: gone through the requirements for the install a server (hardware or virtual one) available for install 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 that you might want to install but are not required (see below).
Operating system
- Install Debian stable – minimal server installation with only openssh-server is recommended.
- Make sure to update all repositories and install all available upgrades if any.
- Make sure to configure your server in your local time zone and ensure, that your server is configured to keep its time in sync (for example, install and configure NTP properly).
- 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.
- Set up the hostname 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, Payara might fail to start by complaining about another process occupying port 4848.
- 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 at least 65536. For how to increase this limitation in Debian, please see the quick install guide below.
- Install a firewall to your operating system (such as ufw) but we recommend, that you install and set up your firewall after the Testlab setup is done and Testlab is verified to be working. This of course only if your server is not connected to a public network during the installation.
- Install the needed X11 libraries to support Java graphics:
# apt-get install libx11-6 libxext6 libxtst6 libxi6 xauth
Fronting Testlab with an Nginx reverse proxy
A recommended configuration for running Testlab is with an Nginx-based reverse proxy. After you’ve successfully set up Testlab, please continue with the guide here and install Nginx in front of your Payara 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 the application server to listen for default 80/443 ports would require the server to be run as a root which is not recommended or supported.
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. The best option is to use a frontend proxy (Nginx) to do this. See “Fronting Testlab with an Nginx reverse proxy” above.
PostgreSQL Database
If you already have the PostgreSQL database set up 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 on the PostgreSQL side.
Keep in mind that the actual database and the user for it are created later on as explained in the 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 10.x version we recommend, or install the version provided by Debian’s own repositories.
Installing PostgreSQL from postgresql.org repository (recommended)
A guide for installing PostgreSQL from postgresql.org can be found here. To keep things short,
1. Register the repository to your Debian:
# apt install curl ca-certificates # install -d /usr/share/postgresql-common/pgdg # curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc
Create /etc/apt/sources.list.d/pgdg.list as.
deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt bullseye-pgdg main
Replace “bullseye” with the Debian release you are installing.
2. Install the software by running
sudo apt-get update sudo apt-get upgrade sudo apt-get install postgresql-16 postgresql-client-16 postgresql-16-pgvector
This will install PostgreSQL 16 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 username and tries to match it to the database username – 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 basically 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/16/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 the 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
The server must have 1.8 Java JDK installed. We recommend running the software with Azul’s OpenJDK JDK. Go to Azul’s Linux download page and download the .TAR package for Java 8 version of the JDK. If there are multiple options available, please download the one with the latest OpenJDK version.
To install Java runtime under /opt in Debian, download the installation package to the /opt directory and run (adjust package name and paths accordingly)
# cd /opt # tar xfz zulu8.76.0.17-ca-jdk8.0.402-linux_x64.tar.gz # rm -f zulu8.76.0.17-ca-jdk8.0.402-linux_x64.tar.gz
Append the directory of your installed JDK 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/zulu8.76.0.17-ca-jdk8.0.402-linux_x64 export PATH=$JAVA_HOME/bin:$PATH
Verify, that the JDK 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 that 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 the Reports menu won’t be accessible.
Creating a user
For security reasons, you should create a technical user on your server to run Testlab. This user will be used to run the Payara 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 Meliora Testlab on a server in which all the necessary configuration is done, PostgreSQL database server and a database are available and all needed server dependencies are installed. 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 of Payara Server and/or Oracle GlassFish can run the needed asadmin commands or configure the settings manually from the DAS if a Windows Server installation is preferred.
Create a database for Testlab
To continue with this chapter, make sure you have: gone through the requirements for the install a server (hardware or virtual one) available for install installed a Linux-operating system with the correct timezone, UTF-8 locale, proper ulimit values, needed dependencies, and networking enabled installed PostgreSQL database configured PostgreSQL to allow connections from your server installed Java JDK with JAVA_HOME and PATH set created an operating system user for running Testlab To create a 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 # psql -c "create extension vector" 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 installation 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 the Payara application server
To continue with this chapter, make sure you have: gone through the requirements for the install a server (hardware or virtual one) available for install installed a Linux-operating system with the correct timezone, UTF-8 locale, proper ulimit values, needed dependencies, and networking enabled. installed PostgreSQL database configured PostgreSQL to allow connections from your server installed Java JDK with JAVA_HOME and PATH set created an operating system user for running Testlab created a database for Testlab made sure, that your server is not already running Payara or any conflicting server software Meliora Testlab runs on the Payara application server. A Bash-based installation script for Linux is provided in the installation package which provides the easiest way to set up the application server environment.
To set up 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. The license key is always required, for evaluation too. If you don’t happen to have one you can request one from us by contacting us.
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 set up the database connection pools and SMTP_ parameters are used to set up 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
- There is no process reserving the needed ports (4848 in this case) – and of course, Payara is not running for some reason.
- The hostname 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 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 application server’s admin account.
This script
- deletes the existing Payara installation from ./payara5 directory if any,
- extracts the Payara application server to the ./payara5 directory,
- copies the needed dependency libraries to the Payara 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 Payara 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 Payara’s admin user,
- enables secure admin mode which allows remote access to the DAS (at port 4848),
- restarts Payara,
- copies Testlab’s evaluation license key file to the correct location and
- deploys the Testlab application to Payara.
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 Payara admin account password for executing the needed asadmin commands.
Something went wrong – I want to run the installer again
If you want to run the installer script again, make sure that Payara is not running. When you run the installer script, it deletes the existing Payara install directory (./payara5) but it might 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 Payara, for example, like
22373 pts/0 Sl 2:13 /opt/.../bin/java -cp /home/testlab/payara5/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 Payara domain configuration with JVM option which reserves 1.5GB (1536MB) of RAM for the server. This is enough for evaluation, but for a good-performing production deployment, we recommend that the heap size be increased.
For example, to increase the heap from 4GB make sure the application server is running and execute
# ./asadmin delete-jvm-options '-Xmx1536m' # ./asadmin create-jvm-options '-Xmx4096m'
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
To continue with this chapter, make sure you have: gone through the requirements for the install a server (hardware or virtual one) available for install installed a Linux-operating system with the correct timezone, UTF-8 locale, proper ulimit values, needed dependencies, and networking enabled installed PostgreSQL database configured PostgreSQL to allow connections from your server installed Java JDK with JAVA_HOME and PATH set created an operating system user for running Testlab created a database for Testlab made sure, that your server is not already running Payara or any conflicting server software placed the testlab_license.key file in the installation directory unzipped the installation package to the installation directory, configured the installation script, and run it without any unexpected errors 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 Payara 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 that 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 of the administrative company administrator account
- E-mail *: E-mail address of the company administrator
- User ID *: A 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 hostname as “testlab” and the host domain as “.mycompany.com“. Values must match 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 Payara.
- HTTPS port *: HTTPS port of the server – defaults to 8181 which is the default HTTPS port of Payara.
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 the URL address end-users will use to access Testlab. - File attachment directory *: Directory on the 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 set up 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 PAYARA_HOME/glassfish/domains/domain1/config directory for later access.
After setup, you should be able to access 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 PAYARA_HOME/glassfish/domains/domain1/lib/classes/testlab.properties configuration file with
setup.disabled=false
and restart Payara to access the setup wizard again.
-
Important files and directories
This chapter lists and describes the relevant files and directories for Testlab installation and maintenance. The shortcuts referred to are
- PAYARA_HOME: The installation directory of the application server – payara5/ if the server is installed with the provided installation script.
- DOMAIN_HOME: The directory of the Payara domain Testlab is running with – PAYARA_HOME/domains/domain1/ if the server is installed with the provided installation script.
Relevant files and directories for an on-premise Testlab installation are:
- PAYARA_HOME/bin/asadmin
An executable to run commands on the Payara 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
Payara 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_ai.log, testlab_ai_audit.log
A log file for Testlab’s AI-related functions. - testlab_api*.log
Log files 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 subsystem. - testlab_import.log
A log file for Testlab’s import-related functions. - testlab_report.log
A log file for Testlab’s report subsystem.
- server.log
- DOMAIN_HOME/config/domain.xml
- The main configuration for the application server domain. It is not advised for this file to be edited by hand but via the DAS (Domain Administration Server) console accessible by default from the 4848 port.
-
Maintenance and backups
Starting and stopping the server
Change to PAYARA_HOME/glassfish/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 Payara 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 back up a Testlab installation the following artifacts should be backed up:
- Testlab’s PostgreSQL database,
- attached files in the server file system,
- PAYARA_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 on how to set up 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 at least 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 Payara 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.
Step 1. Set up an Nginx based reverse proxy on your server to terminate SSL. For instructions on how to do this, see the documentation.
Step 2. 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 do not prefer to run the setup 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.http=80 server.port.https=443 ...
Note: Make sure to restart Payara for the change to take effect.
-
Testlab licensing
Running on-premise Testlab requires a valid license, for evaluation too. A production license is always granted for a single company and tied to a hostname 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 Payara 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 set up 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 a security standpoint. 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 platform 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: 4096MB
- 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, of course, recommended to have this disk space in reserve to make sure you don’t run out of disk space on your machine.
Installing Debian
1. Download Debian 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-x.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 the Domain name blank.
6. Enter a root password, twice, and make sure to remember this.
7. Create a user account for your machine by giving a full name, account username, and 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 of course. 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 the network you can leave this blank.
11. Wait for Debian to continue to install. Answer No 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 the 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 machine in bridged mode or in some other networking configuration that 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 an 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: Payara HTTP listener
- 14848 -> 4848: Payara 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 conflict with port 8080 so we forward 18080 for simplicity’s sake in this how-to. This means of course 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 with your changed values.
Add a 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 hostname 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 an SSH connection to testlab:2222 to make sure port forwarding works as expected
# ssh -p 2222 youruser@testlab ... youruser@testlab:~#
You can also do the configuration directly in the VirtualBox console window but using your local SSH terminal is often more comfortable.
Note that Debian might not allow you to log in as root via SSH. Use the user account created above and change to root (su – root) for administration.
2. Set up limits.conf
# su - root # 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. Select the locale as the default locale for the system environment.
# nano /etc/default/locale
… add (replace with your preferred UTF-8 locale)
LC_ALL=en_US.UTF-8
4. Reboot machine. After reboot login as root again.
# shutdown -r now
5. Install updates and other dependencies
# apt-get update # apt-get upgrade # apt-get install libx11-6 libxext6 libxtst6 libxi6 xauth graphviz unzip
6. Install Java runtime
Download the latest Java 8 JDK .tar.gz-package for Linux x64 architecture from Azul’s Java download page and select Java 8 JDK download link for .TAR package. Transfer the downloaded file to the virtual machine’s /opt directory.
myworkstation# scp -P 2222 zulu8...-linux_x64.tar.gz youruser@testlab:/tmp/
And as root on the virtual machine
# cd /opt # tar xfz /tmp/zulu8...-linux_x64.tar.gz # rm /tmp/zulu8...-linux_x64.tar.gz # nano /etc/profile
… add
export JAVA_HOME=/opt/zulu8...-linux_x64 export PATH=$JAVA_HOME/bin:$PATH
Log out and re-login as root and verify, that the Java runtime is installed correctly.
# exit
… and log in as root and run
# java -version openjdk version "1.8.0_xxx" ...
7. Create a 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
8. Install PostgreSQL
Register the repository to your Debian:
# apt install curl ca-certificates # install -d /usr/share/postgresql-common/pgdg # curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc
Create /etc/apt/sources.list.d/pgdg.list as:
deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt bullseye-pgdg main
(replace “bullseye” with the Debian release you are installing)
2. Install the software by running
sudo apt-get update sudo apt-get upgrade sudo apt-get install postgresql-16 postgresql-client-16 postgresql-16-pgvector
This will install PostgreSQL 16 database software and create the default database.
Database creation
To create a user and a new database for 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 # psql -c "create extension vector" 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 installation to be able to create and re-create the testlab database if needed. Also, the user must own the schema in the database.
Payara and Testlab application installation
All tasks here should be run as a testlab user by running “su – testlab” as a root.
1. Download the Testlab on-premise 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 to the same directory as above.
3. Run the installer script to set up Payara to /home/testlab/payara5 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 Payara admin account: first, when asked for a password enter a blank as the current admin password is empty, and secondly, enter the password for your Payara admin account twice to change it. If the script asks your trust for Payara’s certificate, answer Yes. The deployment of the EAR will give PER01000 related warnings during the installation which is normal and expected.
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 in 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
- backing up your existing database content,
- executing one or more SQL scripts to the Testlab database and
- 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 do not have to be deployed separately for each version. We highly recommend keeping your Testlab up to date to ease up the upgrade process.