Skip to content

Latest commit

 

History

History
517 lines (363 loc) · 19 KB

README.adoc

File metadata and controls

517 lines (363 loc) · 19 KB
Raw

Klaros Test Management Docker-Integration

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.

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.

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.

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

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 .

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.

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

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.

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

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

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

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.

12. FAQ

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

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.

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.

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