Klaros Test Management Docker-Integration

Table of Contents

• 1. Introduction
  • 1.1. About Docker
  • 1.2. About Klaros Test Management
• 2. Prerequisites
• 3. Configuring Docker Environment Variables
  • 3.1. Configuration via the Dockerfile
  • 3.2. Configuration at server startup
  • 3.3. Configuration via a file
• 4. Installation
  • 4.1. Clone
  • 4.2. Build
• 5. Usage
  • 5.1. How to start an instance
  • 5.2. How to shut down your instance
• 6. Create, restore and test a backup
  • 6.1. Creating a backup
  • 6.2. Restore a Backup
  • 6.3. Test a Backup
• 7. How and where can I find the log files?
  • 7.1. Show log files via Docker shell
  • 7.2. Show logs from backup
• 8. Update
  • 8.1. Update via master branch
  • 8.2. Update via tags
  • 8.3. Refresh image
• 9. How to use a previous version
• 10. Uninstallation
• 11. Documentation
• 12. FAQ
• 13. License
• 14. Contact
• 15. Contributing
• 16. Acknowledgements

1. Introduction

❗	This documentation only covers the Klaros Test Management installation with the integrated Apache Derby database and is only supported for test installations. Do not use it for production systems.

The instructions for the production installation with the database systems MariaDB, MSSQL, MySQL and PostgreSQL can be found here.

This documentation shows step by step how to install and configure Klaros Test Management under Docker for Windows and Linux.

1.1. About Docker

Docker is a free container-based software that allows a secure installation of applications on different operating systems such as Windows and Linux.

You can find further information at Why-Docker

1.2. About Klaros Test Management

Klaros Test Management is a professional web-based test management software. It contains components for resource management and evaluation of test activity. Tracking of test requirements is supported, as well as agile development processes. Numerous interfaces with issue trackers, test automation tools and continuous integration servers allow seamless integration into existing development environments.

Klaros Test Management is available free of charge in the Community Edition and can also be used for commercial purposes without restrictions.

The Enterprise Edition offers you the full range of functions, including one-year support and free access to all software updates. An overview of the features of both editions can be found here.

To receive your free 30-day trial license for the Enterprise Edition, you can request your license key here.

Detailed information, extensive documentation, videos and a freely accessible online demo can be found under Klaros Test Management.

(Back to top)

2. Prerequisites

Windows

The current hardware requirements and installation steps are described in the official Docker documentation. The Docker Desktop installation requires a login.

To make it easier to update Klaros Test Management later, it is recommended to use Git to download the Dockerfile from GitHub.

This completes the preparations for Windows. The chapter Installation describes how to use Git Bash to download the Dockerfile and prepare it for future updates.

Linux

See the official Docker documentation for the latest hardware requirements and installation steps.

Ubuntu Docker

Debian Docker

CentOS Docker

RHEL Docker

Under CentOS and RHEL, Podman is a popular alternative to Docker. Since Podman provides similar functions as Docker, the code sections with "docker" only need to be replaced by "podman".

Supported Podman version: 1.4.4

Git is required to successfully download the Klaros Test Management Dockerfile from GitHub.

Git installation via Ubuntu/Debian

sudo apt-get update
sudo apt-get install git

Git installation via CentOS/RHEL

sudo yum check-update
sudo yum install git-core

The following command can be used to check whether the installation was successful

git --version
Output: git version 2.17.1

This completes the preparations for Linux. The chapter Installation describes how the Dockerfile can be downloaded and prepared for future updates.

(Back to top)

3. Configuring Docker Environment Variables

Table 1. Configurable environment variables before the first server start via the Dockerfile

Variable	Default	Description
TOMCAT_ADMIN_PASSWORD	P@ssw0rd	Password for login 127.0.0.1:18080/monitoring
TOMCAT_MEMORY_MIN	128	Minimum available RAM in MB
TOMCAT_MEMORY_MAX	768	Maximum available RAM in MB
JAVA_OPTS		With JAVA_OPTS additional settings can be transferred to the Tomcat server. For example the time zone can be set to Europe/Berlin with JAVA_OPTS -Duser.timezone=Europe/Berlin
KLAROS_VERSION	${KLAROS_VERSION:-5.7.0}	Klaros release version, which is used during installation. A list of available releases can be found on the official Klaros Test Management website or on GitHub

Table 2. Modifiable variables after the first server start via the Dockerfile

TOMCAT_MEMORY_MIN

TOMCAT_MEMORY_MAX

JAVA_OPTS

3.1. Configuration via the Dockerfile

Open the Dockerfile under ~/klaros-docker/ApacheDerby with your preferred text editor. The Dockerfile contains a list of configurable ENV variables. See table 1 for more information.

ℹ️	Please make sure that you recreate the image after changing the Dockerfile.

3.2. Configuration at server startup

Changeable variables can be found in table 2. The environment variables can be changed with the -e parameter.

Example

sudo docker run --name Klaros -p 18080:18080 -e TOMCAT_MEMORY_MAX='1024' -e <Other Variable> klaros

3.3. Configuration via a file

To define the configurations via a file, a text file can be created in the ApacheDerby directory. Modifiable variables can be found in table 2. Add the --env-file parameter when creating the container.

Windows Example

New-Item <Path/env-list.txt> -ItemType file
echo "TOMCAT_MEMORY_MAX=1024" > env-list.txt
sudo docker create --name Klaros -p 18080:18080 --env-file ./env-list.txt klaros

Linux Example

touch env-list
echo "TOMCAT_MEMORY_MAX=1024" > env-list
docker create --name Klaros -p 18080:18080 --env-file ./env-list klaros

(Back to top)

4. Installation

4.1. Clone

Once you are in the directory you want, you can start downloading the Dockerfile

git init
git clone https://github.com/klaros-testmanagement/klaros-docker

With ls you can check whether the directory was created correctly

ls
Output: klaros-docker

4.2. Build

The image is needed to create the Klaros container and start the server.
Windows users are switching from Git Bash to Powershell.

cd ~/klaros-docker/ApacheDerby
docker build -t klaros .

(Back to top)

5. Usage

5.1. How to start an instance

During startup, a Docker-Container with the name "Klaros" will be created.

❗	When the container is created, an anonymous volume is created. If a named volume is desired, -v must be added as an additional parameter.

One-time execution: Create a Klaros container (anonymous volume)

docker create --name Klaros -p 18080:18080 klaros

One-time execution: Create a Klaros container (named volume)

docker create --name Klaros -p 18080:18080 -v klaros-data:/data klaros

Once the container has been created, the server can be booted with docker start

docker start -a Klaros

To execute the container in detached mode, the -a parameter must be removed

docker start Klaros

Details

For more information about the docker start parameters, see the official Docker Documentation.

After the server has been started, the message "Server startup in x ms" appears at the end. You can now use any browser to enter your IP address and port to access the Klaros website.

Example: 127.0.0.1:18080

Username: admin
Password: admin

Another Klaros instance can be used to try a new Klaros version or to test an existing backup. To create another instance, simply change the container name and port.

Create a second Klaros instance with its own database

docker create --name Klaros2 -p 18081:18080 klaros

5.2. How to shut down your instance

If the container was started in the foreground, you can shut down the server with the key combination CTRL + C (only possible for Linux).

Alternatively the server can also be shut down via docker stop Klaros.

(Back to top)

6. Create, restore and test a backup

Backups are labeled with the name "backup_klaros<date>.tar.gz". If you create several backups per day, it is recommended to specify a time (hours, minutes and seconds) when creating the backups. To do this, add %H(hour), %M(minute), and %S(second) in date/Get-Date.

ℹ️	If an error occurs while creating a backup, the log files provide traceable procedures for the error messages.

Windows Example

$(Get-Date -UFormat "%y-%m-%d-%Hh-%Mm-%Ss")

Linux Example

$(date '+%y-%m-%d-%H:%M:%S')

Details

This would give the backup the following name:

Windows: backup_klaros19-10-28-11h-34m-33s.tar.gz
Linux: backup_klaros19-10-28-11:34:33.tar.gz

You can change the backup path by changing the code section after "-v".

Windows Example

mkdir ~/klaros-docker/Path/backup
docker run --rm --volumes-from Klaros -v ~/klaros-docker/Path/backup:/backup alpine tar cvzf /backup/backup_klaros$(Get-Date -UFormat "%y-%m-%d").tar.gz /data/klaros-home /data/catalina-base/logs

Linux Example

mkdir ~/klaros-docker/Path/backup
sudo docker run --rm --volumes-from Klaros -v ~/klaros-docker/Path/backup:/backup alpine tar cvzf /backup/backup_klaros$(date '+%y-%m-%d').tar.gz /data/klaros-home /data/catalina-base/logs

6.1. Creating a backup

Windows

docker stop Klaros
mkdir ~/klaros-docker/backup
docker run --rm --volumes-from Klaros -v ~/klaros-docker/backup:/backup alpine tar cvzf /backup/backup_klaros$(Get-Date -UFormat "%y-%m-%d").tar.gz /data/klaros-home /data/catalina-base/logs

Linux

sudo docker ps
sudo docker stop Klaros
sudo docker run --rm --volumes-from Klaros -v ~/klaros-docker/backup:/backup alpine tar cvzf /backup/backup_klaros$(date '+%y-%m-%d').tar.gz /data/klaros-home /data/catalina-base/logs

6.2. Restore a Backup

❗	The container must be shut down before restoration.

ℹ️	Note to adjust the date of the respective backups.

docker stop Klaros
docker run --rm --volumes-from Klaros -v ~/klaros-docker/backup:/backup alpine /bin/sh -c "cd /data && tar xvzf /backup/backup_klaros19-10-28.tar.gz --strip 1"
docker start -a Klaros

6.3. Test a Backup

ℹ️	Note to adjust the date of the respective backups.

To test a backup, you can create a second Klaros instance to install the backup on. The second instance must be fully booted once before the backup can be installed.

Start a second Klaros instance

docker run --name Klaros-test -p 18081:18080 klaros

The server is then stopped with CTRL + C or with docker stop Klaros-test

docker stop Klaros-test

Now the backup to be tested is uploaded to the volume of "Klaros-test" and the server is started

docker run --rm --volumes-from Klaros-test -v ~/klaros-docker/backup:/backup alpine /bin/sh -c "cd /data && tar xvzf /backup/backup_klaros19-10-28.tar.gz --strip 1"
docker start -a Klaros-test

If the backup has been successfully tested, the server can be stopped and removed.

docker stop Klaros-test
docker rm -v Klaros-test

(Back to top)

7. How and where can I find the log files?

Log files may be required for troubleshooting. To access log files, a shell can be opened directly in the Docker-Container or they can be taken from the backup.

Relevant log files can be found here:

/data/catalina-base/logs

7.1. Show log files via Docker shell

In the Klaros container, open a shell with docker exec to get access to the logs.

ℹ️	Please note that the server must be started when accessing via the shell and is not shut down.

The log files can then be read using more

docker exec -it klaros_db /bin/sh
more /data/catalina-base/logs/catalina.2019-12-09.log

7.2. Show logs from backup

Windows

Windows users can use the WinRAR archive program to extract .tar.gz archives.

Afterwards, the Klaros Test Management logs can be displayed in the "logs" folder of catalina-base.

Linux

To read the logs from the backup, use tar to unpack the archive

sudo tar -xzf backup_klaros19-10-28.tar.gz

Afterwards, the Klaros Test Management logs can be displayed in the "logs" folder of catalina-base.

(Back to top)

8. Update

❗	After an update of Klaros Test Management, it is no longer possible to install the previous version. Also make sure to refresh the image after the update, otherwise the previous version will still be used.

Before an update of Klaros Test Management can be performed, a temporary container with the volumes of Klaros must be created

docker stop Klaros
docker create --name Klaros-tmp --volumes-from Klaros alpine
docker rm Klaros

8.1. Update via master branch

Klaros can be updated to the latest version with git pull

git pull origin master

8.2. Update via tags

To perform an update from an older to a newer version, the first step is to search for new updates in the GitHub repository. Current versions can be viewed via git tag. Then a local branch "update" with the desired version can be created and merged. Alternatively, you can merge your local branch directly with the master instead of creating a second branch.

git checkout master
git pull origin master
git checkout tags/<tag_name> -b update
git checkout klaros
git merge update
git branch -D update

8.3. Refresh image

After downloading the update from the GitHub repository, a new image is created and all dangling images are removed

docker stop Klaros
docker build -t klaros .
docker image prune

After the new image has been created, the server will be created with the volumes of Klaros-tmp and the temporary container will be removed. Afterwards the server can be started as usual.

docker create --name Klaros --volumes-from Klaros-tmp -p 18080:18080 klaros
docker rm Klaros-tmp
docker start -a Klaros

(Back to top)

9. How to use a previous version

❗	If a newer version is already in use, then an older version can only be used by creating a new instance or a re-installation.

You can view currently supported versions on GitHub releases.

After the repository has been cloned, the tags can be listed using git tag and with git checkout tags/<tag_name> -b <new_branch> a new branch is created and checked out.

git tag
git checkout tags/<tag_name> -b klaros

(Back to top)

10. Uninstallation

To completely remove Klaros Test Management from Docker, the container must be stopped first, before the container and volume can be removed.

Then remove the ~/klaros-docker directory and the image.

docker stop Klaros
docker rm -v Klaros
docker rmi klaros
rm -rf ~/klaros-docker

(Back to top)

11. Documentation

You will find information on how to get started with Klaros Test Management in our tutorial and in the user manual. Both are available in the application itself after successful login.

Our installation documentation contains a description of how to install Klaros Test Management under Docker for ApacheDerby, MariaDB, MSSQL, MySQL and PostgreSQL databases.

(Back to top)

12. FAQ

A technical FAQ as well as a FAQ on prices, ordering and delivery can be found on our website.

(Back to top)

13. License

Klaros Test Management for Docker is licensed under the terms of the MIT License.

By installing our software through Docker, you also agree to our Limited Use Software License Agreement.

(Back to top)

14. Contact

We hope that we have given you a smooth start with this description.

If you have any questions, requests or just want to give feedback, please write to us at [email protected] or use our forum.

(Back to top)

15. Contributing

Would you like to help us or make suggestions for improvement? Follow these steps to suggest your changes.

• Create an issue and describe your idea

• Fork the repo

• Create a new branch (git checkout -b feature/my-idea)

• Make your changes

• Commit your changes (git commit -am 'Adding feature')

• Push to your branch (git push origin feature/my-idea)

• Create a Pull Request

(Back to top)

16. Acknowledgements

• André Raabe for providing the Apache Derby and Microsoft SQL Server Version

• Adam Warner for providing the GHA workflow to publish pre-built images to ghcr.io and tweaking the Microsoft SQL Server version to allow for remote instances

(Back to top)