Chapter 3. Installation

Depending on the version of Klaros-Test­management in use, a different user license model is applied. Since the Klaros-Test­management Community Edition has a smaller number of features in comparison to the other editions it supports an unlimited amount of users that can work in parallel. The Klaros-Test­management Enterprise Edition follows another license model. Each Klaros-Test­management Enterprise Edition license is bound to a set number of licensed users. This number dictates how many users can be active at any single point in time. If a user is to be created which would excess the number of licensed users, this user immediately gets deactivated thereafter. The user can later be re-activated if another active user gets deactivated first.

To access Klaros-Test­management, a modern web browser supporting JavaScript is required.

	Caution
	Klaros-Test­management requires a minimum screen resolution of 1280x1024 pixels.

To run the Klaros-Test­management server, a Microsoft Windows or Linux operating system running OpenJDK 8 or Oracle Java 8 is required.

	Warning
	Later Java Runtime versions, especially non LTS (Long Test Support) releases (Java 9, 10, 12, 13) are currently not supported. Java 11 (LTS) will be supported in the next major version 5.0.

For optimal performance, using a separate database installation is highly recommended. This database is not required to run on the same physical machine as the Klaros-Test­management server.

3.2.2.1. Installing Java

If your system is not yet equipped with a Java 8 runtime environment, you need to download and install a JRE or JDK distribution. Both JRE and JDK installations are supported. For maximum performance choose a distribution matching your system architecture (x86/x64).

Make sure that the JAVA_HOME/JRE_HOME environment variable is set!

A common caveat is that although Java is installed on your machine, the installer or launch script will complain that neither the JAVA_HOME nor the JRE_HOME environment variable is defined. Windows users will find an option to set this in their computer control panel. The instructions to reach this vary with different versions of windows, an example is shown below. Linux users should set these variables in their startup scripts. If you have installed a Java SDK you would set the JAVA_HOME variable. If your system only contains a Java Runtime (JRE) please use JRE_HOME accordingly.

3.2.2.1.1. Downloading OpenJDK

Free OpenJDK distributions may be downloaded from the following URL: https://adoptopenjdk.net/.

OpenJDK distributions are open sourced licenced and available for free.

3.2.2.1.2. Downloading Oracle Java

A current Oracle Java SE Runtime installer can be downloaded from this URL: http://www.oracle.com/technetwork/java/javase/downloads/.

Please note that starting April 16, 2019 Oracle has changed the license terms for their Java SE distributions. For using them in a non personal / non development environment a commercial license must be acquired. Details can be found at https://www.oracle.com/downloads/licenses/javase-license1.html.

3.2.2.2. Setting the JAVA_HOME/JRE_HOME environment variable under Windows

Depending on your Java runtime selection use JAVA_HOME or JRE_HOME in the following settings.

• Go to Control Panel.

• Find System.

• Then go to Advanced system settings

• Click on the panel Advanced then the button Environment Variables

• Then this Window should pop up.

If the variable JAVA_HOME (or JRE_HOME) is not listed, press New. Otherwise make sure the variable value of JAVA_HOME (or JRE_HOME) is still correct.

If the name of the variable is JAVA_HOME, the value must be the absolute path of the Java JDK. You can usually find the JDK in C:\Program Files\Java\jdk1.8.0_nn, where nn is the patch level of the JDK. Java JREs, which are addressed via JRE_HOME can be found in C:\Program Files\Java\jre1.8.0_nn, where nn is the patch level of the JRE. Add (x86) to C:\Program Files if you use a 32bit Java on a 64bit operating system, which is not recommended for production use).

After pressing OK the Java variable is set.

In the end, it should look something like this:

	Never point JAVA_HOME to a JRE directory!
	JAVA_HOME should only be used for JDK installations. JRE_HOME should be used accordingly for JRE-only installations. Else your Windows service may not be able pick up the correct path to your java executable.

3.2.2.5. Disc Space

Klaros-Test­management stores binary attachments in a file based repository inside the .klaros folder in home directory of the user account that is running the Klaros-Test­management application server. Depending on the usage pattern a sufficient amount of disk space should be reserved for this account. If the file based Derby database is active, the database files will per default also be located in the user home directory.

	Note
	Reserving 10GB of disc space should be enough for typical usage patterns.

Upon startup the installer is requesting the language used throughout the following installation procedure.

Currently both English and German are available as a language.

Figure 3.1. Welcome Screen

The initial step shows a welcome screen to the user ( Figure 3.2).

Figure 3.2. Welcome Screen

The installation may be aborted by clicking the Quit button. Clicking Next proceeds with the installation.

The second step shows information about the product and the revision history, listing the fixed issues and the newly added features ( Figure 3.3).

Figure 3.3. Information Screen

The installation may be aborted by clicking the Quit button. Clicking Previous goes back to the Welcome step and clicking Next proceeds with the installation.

The third step shows information about the license agreement for Klaros-Test­management. The license must be accepted to continue the installation. ( Figure 3.4).

Figure 3.4. Licensing Agreement Screen

The installation may be aborted by clicking the Quit button. Clicking Previous goes back to the Information step and clicking Next proceeds with the installation.

The fourth step requests the target path where Klaros-Test­management will be installed. The user can use the Browse button to search for the specific path in the local file system ( Figure 3.5).

Important

It is not recommended to install Klaros-Test­management in the Programs folder on systems running Microsoft Windows Vista or later. By default, Klaros-Test­management will not be able to start if installed here, as tomcat requires write access to the install folder in order to deploy the web application. This is blocked by Microsoft Windows User Account Control (UAC). If you wish to install Klaros-Test­management in this location, UAC must be disabled.

Figure 3.5. Target Path Screen

The installation may be aborted by clicking the Quit button. Clicking Previous goes back to the Licensing Agreement dialog and clicking Next proceeds with the installation.

The fifth step allows to select the packages that are installed with Klaros-Test­management.

Figure 3.6. Select Installation Packages Screen

The installation may be aborted by clicking the Quit button. Clicking Previous goes back to the Target Path dialog, clicking Next proceeds with the installation.

In the sixth step the Tomcat server settings can be changed.

Figure 3.7. User Data Screen

It is possible to set the ports used by Tomcat(Server-Port, HTTP-Port and AJP/1.3-Port), the minimum and maximum amount of memory available to the Tomcat process as well as the user name and password of the Tomcat application server administrator.

In addition it is possible to control the startup of the application during the installation. If the Launch Application Server checkmark is set, the application server will be launched automatically during the installation process. If the Launch Browser checkmark is set, a native web browser instance will be redirected to the application login page. Both of these actions happen during the Section 3.3.9, “Step 8: Perform External Processes” phase.

The installation may be aborted by clicking the Quit button. Clicking Previous button goes back to the Select Installation Packages step and clicking Next button proceeds with the installation.

The seventh step starts the installation of Klaros-Test­management and shows its progress. The following screenshots show the Installation in Progress Screen and the Installation finished screen ( Figure 3.8).

Figure 3.8. Installation in Progress Screen

Figure 3.9. Installation Finished Screen

The installation may be aborted by clicking the Quit button. Clicking Next proceeds with the installation.

The optional eighth step performs external processes such as setting the environment variables and starting the Tomcat service. In case none of the flags Launch Application Server and Launch Browser are checked, this panel will be skipped.

Figure 3.10. Perform External Processes Screen

The installation may be aborted by clicking the Quit button. Clicking Next proceeds with the installation.

The ninth step requests the options for shortcuts. The installer can create shortcuts in the Start-Menu and on the desktop ( Figure 3.11).

Figure 3.11. Setup Shortcuts Screen

This step looks different on Linux installations but has the same functionality.

The installation may be aborted by clicking the Quit button. Clicking Previous goes back to the Perform External Processes step and clicking Nextproceeds with the installation.

The tenth step notifies the user that Klaros-Test­management was installed successfully and shows the path to the uninstaller program ( Figure 3.12).

Figure 3.12. Installation Finished Screen

The Generate an automatic installation script button saves a complete script of the installation with the selected user choices, so that the same installation could be repeated unattended or on other machines.

The installation can be completed by clicking the Done button.

The Language Panel ( Section 3.3.1, “Language Selection”) is displayed and wants to be committed by 0+Enter for English or 1+Enter for German.

    Select your language
    0  [x] eng
    1  [ ] deu
    Enter selection:

The Welcome Panel ( Section 3.3.2, “Step 1: Welcome”) is displayed and wants to be committed by 1+Enter.

    -----------------------------------------------------------------------------------------
    Information
    -----------------------------------------------------------------------------------------


    Version 4.7.0
    (c) Copyright 2009-2017 verit Informationssysteme GmbH. All Rights Reserved.



    Press 1 to continue, 2 to quit, 3 to redisplay
    1

The Information Panel ( Section 3.3.3, “Step 2: Information”) displays the Release Notes of the recent versions starting with version 4.4.0.

    ...

    Version 4.5.2 - 2016-07-06:
    ---------------------------


    Fixed Bugs:

      [KLAROS-2987] - Wrong number of requirements on the iteration detail page after switching the
        connected RMS
      [KLAROS-2981] - Implement a migrator to merge test case step shadows with the same search hash
      [KLAROS-2975] - If a user defined enum field has n entries and a default value set at position n, 
        the entries between n and m can't be selected
      [KLAROS-2974] - Adding project roles on a user details page while editing other properties of the 
        user causes a MethodNotFoundException

    Improvements:

      [KLAROS-2989] - Extend the user printpage for the access rights
      [KLAROS-2979] - Optionally show test case details (steps, precondition, etc) on the test suite print
        page
      [KLAROS-2510] - The detail page result pages should support a bulk print page

    ...

    Version 4.4.0 - 2016-02-12:
    ---------------------------

    New Features:

      [KLAROS-2790] - Implement a RESTful API to retrieve data from Klaros
      [KLAROS-2762] - Synchronisation of attachments from remote requirements management systems
      [KLAROS-2705] - Support the category based filtering on more pages
      [KLAROS-2700] - Enable the input of references to custom properties of text fields of selected test
        artifacts (e.g. %testrun.customPropertyName%) which will be resolved to the respective value when
        viewing them during a test run
      [KLAROS-2696] - Support the Jira REST interface
      [KLAROS-2694] - Synchronize requirements from external systems, e.g. Jira
      [KLAROS-2688] - Add support for the GitHub issue tracker
      [KLAROS-2410] - Add the possibility to create review jobs for test cases from within the test case
        details page
      [KLAROS-1326] - Provide support for specifying test result types in the Jenkins plugin

    Fixed Bugs:

      [KLAROS-2831] - Unable to deselect assignees and categories when creating or editing Redmine issues
      [KLAROS-2825] - Unable to delete test cases containing only deleted test results
      [KLAROS-2817] - Test case steps without associated test cases are present in the database
      [KLAROS-2813] - Start background issue synchronization only after a successful migration
      [KLAROS-2803] - When adding an issue during manual test execution, provide a back button
      [KLAROS-2802] - Some dated test case step results and testsuite results don't have any verdict set
      [KLAROS-2801] - Broken error handling for users attempting to edit their own account in special
        cases
      [KLAROS-2788] - Error during saving of categories

    Improvements:

      [KLAROS-2836] - Add related job information to the test result page
      [KLAROS-2799] - Document how to use the Klaros Remote API
      [KLAROS-2794] - Random errors in database search indices no longer lead to application lockup since
        indices are now automatically rebuild
      [KLAROS-2792] - Lift the artificial file size limit when interactively uploading automated test
        result files
      [KLAROS-2791] - Provide more predefined Reports
      [KLAROS-2771] - Support changing the status of redmine issues
      [KLAROS-2769] - Add support for the GoogleTest result file format
      [KLAROS-2768] - Add support for the gtester result file format
      [KLAROS-2767] - Add support for the JsUnit result file format
      [KLAROS-2766] - Add support for the TESSY result file format
      [KLAROS-2765] - Add support for the JBehave result file format
      [KLAROS-2764] - Add support for the embUnit result file format
      [KLAROS-2754] - After successfully validating a connection to an IMS or RMS, allow to save the used
        credentials for background authentication
      [KLAROS-2720] - Support detecting issue resolve states in the report model API
      [KLAROS-2719] - Check for matching content in the target url when checking external system urls
      [KLAROS-2715] - Provide a remote issue url through the model API
      [KLAROS-2713] - Extend the model API to deliver browse URLs to remote issue management systems
      [KLAROS-2466] - Calculate the estimated time left automatically when logging work
      [KLAROS-2425] - Support build environment and build parameter variables as parameters in the Jenkins
        Plugin
      [KLAROS-2163] - Rename the "Area" field in test case definitions to "Test Type" to comply with ISTQB




    Press 1 to continue, 2 to quit, 3 to redisplay
    1

The License Panel ( Section 3.3.4, “Step 3: Licensing Agreements”) displays the Licensing Agreements. Commit with 1+Enter.

    -----------------------------------------------------------------------------------------
    Licensing Agreements
    -----------------------------------------------------------------------------------------
     
    Limited Use Software License Agreement
    
    PLEASE READ THIS AGREEMENT CAREFULLY BEFORE ATTEMPTING TO USE THE
    SOFTWARE OF verit Informationssysteme GmbH AND RELATED DOCUMENTATION
    (COLLECTIVELY, THE "SOFTWARE") AND BEFORE INSTALLING OR USING THE
    SOFTWARE. BY INSTALLING OR USING THE SOFTWARE, YOU ARE CONSENTING
    TO BE BOUND BY THIS AGREEMENT.

    ...

    limitations may not apply to you. You may also have other rights
    that vary from state to state.

    Press 1 to accept, 2 to reject, 3 to redisplay
    1

The Target Path Panel ( Section 3.3.5, “Step 4: Target Path”) looks like this with the console installer:

    -----------------------------------------------------------------------------------------
    Target Path  
    -----------------------------------------------------------------------------------------
    
    
    Select the installation path: [C:\Users\...\Klaros-Testmanagement]

You can press Enter to accept the proposed path or type another. The path will be created, if it did not already exist. If the directory already exists, a warning is displayed and you can cancel the installation or continue.

Select Installation Packages ( Section 3.3.6, “Step 5: Select Installation Packages”) is more complex in console mode. The required packages (Tomcat 8 and Klaros-Test­management) are displayed for information only and the request targets the optional PDF-Documentation. Typing Y chooses to install the PDF-Documentation, where N omits it. After this choice you are requested to commit the selection by typing 1 and then Enter.

    -----------------------------------------------------------------------------------------
    Select Installation Packages
    -----------------------------------------------------------------------------------------
    
    Select the packs you want to install:

      [x] Pack 'Tomcat 8 Application Server' required
      [x] Pack 'Klaros-Testmanagement 4.6.4' required
    -----------------------------------------------
      [x] Include optional pack 'PDF-Documentation'
    -----------------------------------------------
    Enter Y for Yes, N for No: N
    Y
    Done!

    Press 1 to continue, 2 to quit, 3 to redisplay
    1

After that, the installer requests user data ( Section 3.3.7, “Step 6: User Data”). The installer presents default values which can be comitted by pressing Enter. You can enter a different value in case the default is not suitable.Checkboxes show [x] if the checkbox is set, [ ] otherwise. Pressing Enteraccepts the current value, which can be set and unset explicitly with 1and 0respectively.

In this example we adopt most of the default values. Only the memory settings and the tomcat admin password (withno default) are entered and the two flags are unset:

    -----------------------------------------------------------------------------------------
    User Data
    -----------------------------------------------------------------------------------------  
    Tomcat Server Settings:

    Server-Port: [18005]
    
    HTTP-Port: [18080]
    
    AJP/1.3-Port: [18009]
    
    Session Timeout: [60]

    The minimum and maximum amount of memory available to the Tomcat process:
    Minimum (MB): [256] 
    400
    Maximum (MB): [512] 
    1024

    The username and the password of the administrator account for managing the Tomcat server:
    Username: [admin]

    Password:
    **********
    Retype Password:
    **********
    
    ------------------------------------------
      [x] Launch Application Server
    Enter 1 to select, 0 to deselect:
    0

      [x] Launch Browser
    Enter 1 to select, 0 to deselect:
    0


    Press 1 to continue, 2 to quit, 3 to redisplay
    1

Packages are displayed as soon as they are installed ( Section 3.3.8, “Step 7: Installation”).

    [ Starting to unpack ]
    [ Processing package: Tomcat 7 Application Server (1/3) ]
    [ Processing package: Klaros-Testmanagement (2/3) ]
    [ Processing package: PDF-Documentation (3/3) ]
    [ Unpacking finished ]
    Installation finished

This panel is skipped since we chose not to launch the server or a browser, otherwise startup messages of the server could be seen here. See Section 3.3.9, “Step 8: Perform External Processes” on how this is handled in GUI mode.

In a GUI-less environment we do not want any menu entries or icons on desktops, thus we choose N. See Section 3.3.10, “Step 9: Setup Shortcuts” for details on shortcut setup in windowed environments.

    -----------------------------------------------------------------------------------------
    Setup Shortcuts
    -----------------------------------------------------------------------------------------
    
    ----------------------------------    
    Create shortcuts in the Start-Menu
    ----------------------------------
    Enter Y for Yes, N for No: 
    N
    ------------------------------------------
    Create additional shortcuts on the desktop
    ------------------------------------------
    Enter Y for Yes, N for No:
    N

An automatic installation script with the selected user choices can be genrated here, so that the same installation could be repeated unattended or on other machines. Automatic installation scripts will work for unattended installations in console mode as well.

    Generate an automatic installation script
    Enter Y for Yes, N for No:
    Y
    Select the installation script (path must be absolute)[C:\Users\...\Klaros-Testmanagement
      \auto-install.xml]

    Installation was successful
    Application installed on C:\Users\...\Klaros-Testmanagement
    [ Writing the uninstaller data ... ]
    [ Console installation done ]

After the installation has finished, you can find the installation of Klaros-Test­management in the folder /opt/klaros-testmanagement. See Section 3.10, “Installing Klaros-Test­management as a Service” for details on how to configure Klaros-Test­management to run as a service.

If you're trying to install a new version of Klaros-Test­management in some cases you will receive the message Incompatible installation detected. (see Figure 3.13, “Incompatible Installation detected”). In this case, Klaros-Test­management needs to be uninstalled first before a new version can be installed. As with the update process, all of your settings, database settings and the content repository will remain untouched by the uninstallation process.

Figure 3.13. Incompatible Installation detected

When uninstalling Klaros-Test­management, the Force the deletion of [Klaros-Test­management installation path] checkbox needs to be set.

Figure 3.14. The Uninstaller

Some settings may need manual adjustments when updating Klaros-Test­management from major revision 3 to 4, e.g. from 3.8.4 to 4.0.0.

http://jboss.com/products/seam/pdf

http://jboss.org/schema/seam/pdf

http://jboss.com/products/seam/excel

http://jboss.org/schema/seam/excel

Unexpected runtime exception: The rendered document has not been found in the document store

After updating Klaros-Test­management to a newer version it is possible that a database migration will be necessary. If so, Klaros-Test­management will show the following screen on startup. To start the migration an administrator account is needed. Before the migration process starts, the appropriate authentication domain should be selected ( LDAP or KLAROS). Figure 3.15

Figure 3.15. Database Migration

The log files for Klaros-Test­management can be found in the logs folder in the installation directory and also in condensed form the logs folder within the .klaros directory.

Attaching the log files from these locations to a bug report helps the support team to quickly identify and fix any problems you encounter.

The Hibernate properties file is located at .klaros/hibernate.properties. This file is used to specify the database to use for Klaros-Test­management. It contains the database type, URI and the authentication information. More information about changing the database can be found in Section 3.9, “Changing the Default Database”.

Klaros-Test­management may be customized to add new languages. This process is described in Section 4.1.1, “Defining Language Files”. The file used to store the Quote of the Day entries is located at .klaros/resources/quotes.txt.

The file used to store the Quote of the Day entries is located at .klaros/resources/quotes.txt.

If you are using the default Derby database, this is located in the .klaros/KlarosDerby folder.

All attachments are saved in the .klaros/repository folder. If the Klaros-Test­management installation and database are migrated to a different location this folder should be moved with them.

Depending on your Linux distribution system services are launched using different init daemons.

We are providing sample scripts for the most common ones here, SysVInit and systemd.

  #!/bin/bash
  #
  #
  # This will be ignored by systems that don't use chkconfig.
  # chkconfig: 345 98 2
  # description: klaros (inside Tomcat, a servlet container)
  #
  ### BEGIN INIT INFO
  # Provides:          klaros
  # Required-Start:
  # Required-Stop:
  # Default-Start:     3 4 5
  # Default-Stop:      0 1 2 6
  # Short-Description: klaros
  # Description:       klaros-testmanagement
  ### END INIT INFO
  #
  KLAROS_USER=klarosdemo
  KLAROS_PATH="/opt/klaros-testmanagement"
  /bin/su - "${KLAROS_USER}" -c "${KLAROS_PATH}/bin/catalina.sh $@ >/var/tmp/klaros.log 2>&1"

  [Unit]
Description=Klaros Testmanagement Service
After=syslog.target network.target

[Service]
Type=forking
User=klaros

ExecStart=/opt/klaros-testmanagement/bin/startup.sh
ExecStop=/opt/klaros-testmanagement/bin/shutdown.sh

[Install]
WantedBy=multi-user.target

Under the Windows operating system family the supplied service.bat script can be used to install the Tomcat application server as a Windows service.

Please refer to the official Apache Tomcat 8 Windows service HOW-TO for further details.

Change the Service User Account!

Per default the created Windows service will use the LocalSystem account to run the Klaros-Test­management application. This setting must be changed to the account of the user you intend to use for running Klaros-Test­management in the service account settings. This change is needed due to the fact that the default location for the .klaros folder in the user account home. Skipping this vital step will lead to a newly created .klaros home folder in the C:\Windows\System32\systemuser folder (this location may vary with your Windows version in use; newer version may use C:\Windows\system32\config\systemprofile instead) containing a new empty database, which will now be used by the service instead of the database present when starting Tomcat manually. If you encounter this situation, then shut down the service, delete the .klaros folder in the Windows\System32 folder, change the user account settings of the service and finally restart the service.

Make sure to use a Java architecture that matches your Tomcat installation

Upon first installation of Klaros-Test­management the installer chooses a matching Tomcat Windows installation (32-Bit vs. 64-Bit) for the Java runtime architecture it was started with. If you want to change the desired Java Runtime Architecture later (e.g. switching from 32-Bit Java to 64-Bit Java) please make sure that you re-install your distribution with the desired Java runtime in your system path. If in doubt check by running javaw -version from the cmd windows command line processor. The service will refuse to start if you choose the wrong Java architecture. A typical error output for running a 32-Bit Tomcat installation in conjunction with a 64-Bit Java looks like the following: Commons Daemon procrun (1.0.15.0 32-bit) started Debugging 'tomcat7' service... Starting service... %1 is not a valid Win32 application. Failed creating java C:\Program Files\Java\jre1.8.0_45\bin\server\jvm.dll %1 is not a valid Win32 application. ServiceStart returned 1 %1 is not a valid Win32 application. Debug service finished with exit code 1 Commons Daemon procrun failed with exit value: 3 (Failed to run service as console application) %1 is not a valid Win32 application. You may update the Java virtual machine which the service uses in the Java tab of the tomcat8w administration interface.

Adjusting memory settings

Depending on the number of parallel users, Klaros-Test­management may require a larger amount of memory than the installer suggests with the default values provided. If you want to change the specified memory settings for an already installed installation you may supply these settings in the tomcat8w administration interface as shown below. To ensure that indeed the settings of the installed service are changed, add the service name as a command line argument as follows: [path]\Klaros-Testmanagement\bin\Tomcat8w.exe //ES//Tomcat8. Figure 3.16. Additional Tomcat memory settings

To allow the connection of Klaros-Test­management to the Jira server instance the Jira RPC Plugin has to be activated in your Jira installation. You find this option as Accept remote API calls in General Configuration under Global Settings. Then you need to enable the JIRA RPC Plugin in Plugins under System in the left-hand menu.

	Jira Cloud instances
	Starting April 25th 2019 Atlassian limited access to their cloud instances to token based authentication, so authenticating via username and password is no longer supported. Klaros-Test­management is supporting token based authentication scheme as well. Just use your email address as username and the token as password.

The Klaros-Test­management Trac integration requires the installation of the TracXMLRPC Plugin. The download archives and installation notes are available at http://trac-hacks.org/wiki/XmlRpcPlugin/. After successful installation of the plugin, it has to be activated using the Trac web administration interface. Figure 3.18, “Trac Plugin Section” shows the Trac Plugin section after the successful installation of the plugin.

Figure 3.18. Trac Plugin Section

To make the plugin accessible, authenticated users must be able to access the XML_RPC plugin as shown below.

Figure 3.19. Trac Permissions Section

The following combinations have been successfully tested:

Later versions are expected to work but currently not tested.