Skip to content

Latest commit

 

History

History
516 lines (363 loc) · 20.6 KB

README-German.adoc

File metadata and controls

516 lines (363 loc) · 20.6 KB
Raw

Klaros-Testmanagement Docker-Integration

Version 5.7.0 green License MIT green Community%20Edition FREE green Klaros TM?style=social

Inhaltsverzeichnis

1. Einführung

❗
 Diese Dokumentation deckt nur die Klaros-Testmanagement Installation mit der integrierten Apache Derby-Datenbank ab und wird nur für Testinstallationen unterstützt. Verwenden Sie es nicht für Produktionssysteme.

Die Anleitung für die Produktionsinstallation mit den Datenbanksystemen MariaDB, MSSQL, MySQL und PostgreSQL finden Sie hier.

In dieser Dokumentation wird Schritt für Schritt gezeigt, wie die Installation und Konfiguration von Klaros-Testmanagement unter Docker für Windows und Linux durchgeführt wird.

1.1. Über Docker

Docker ist eine freie, containerbasierte Software, die eine sichere Installation von Anwendungen auf verschiedenen Betriebssystemen wie Windows und Linux ermöglicht.

Ausführliche Informationen dazu finden Sie unter Why-Docker.

1.2. Über Klaros-Testmanagement

Klaros-Testmanagement ist eine professionelle webbasierte Testmanagement-Software. Sie enthält Komponenten für das Ressourcenmanagement und die Auswertung der Testaktivität. Die Verfolgung von Testanforderungen wird ebenso unterstützt wie agile Entwicklungsprozesse. Zahlreiche Schnittstellen zu Issue Trackern, Testautomatisierungstools und Continuous Integration Servern ermöglichen eine nahtlose Integration in bestehende Entwicklungsumgebungen.

Klaros-Testmanagement ist in der Community Edition kostenlos erhältlich und uneingeschränkt auch für kommerzielle Zwecke einsetzbar.

Die Enterprise Edition bietet Ihnen den vollen Funktionsumfang, inklusive einjährigem Support und kostenlosem Zugriff auf alle Software-Updates. Eine Feature-Übersicht der beiden Editionen sehen Sie hier.

Eine kostenlose 30-tägige Testlizenz für die Enterprise Edition, können Sie hier anfordern.

Ausführliche Informationen, umfangreiche Dokumentationen, Videos sowie eine frei zugängliche Online-Demo finden Sie unter Klaros-Testmanagement.

2. Voraussetzungen

Windows

Die aktuellen Hardwareanforderungen und Installationsschritte sind in der offiziellen Docker-Dokumentation beschrieben. Für die Installation von Docker Desktop ist eine Anmeldung erforderlich.

Um das spätere Aktualisieren von Klaros-Testmanagement zu erleichtern, wird empfohlen, das Dockerfile von GitHub mit Git herunterzuladen.

Damit sind die Vorbereitungen für Windows abgeschlossen. Im Kapitel Installation wird beschrieben, wie das Dockerfile mithilfe von Git Bash heruntergeladen und für zukünftige Updates vorbereitet werden kann.

Linux

Auf der offiziellen Docker-Dokumentation sind die aktuellen Hardwareanforderungen und Installationsschritte zu finden.

Unter CentOS und RHEL ist Podman eine beliebte Alternative gegenüber Docker. Da Podman ähnliche Funktionen wie Docker zur Verfügung stellt, müssen die Codeabschnitte mit „docker“ lediglich durch „podman“ ersetzt werden.

Unterstützte Podman-Version: 1.4.4

Git ist erforderlich, um das Klaros-Testmanagement Dockerfile erfolgreich von GitHub herunterzuladen.

Git-Installation über Ubuntu/Debian
sudo apt-get update
sudo apt-get install git
Git-Installation über CentOS/RHEL
sudo yum check-update
sudo yum install git-core

Ob die Installation erfolgreich war, lässt sich mit folgendem Kommando überprüfen:

git --version
Ausgabe: git version 2.17.1

Damit sind die Vorbereitungen für Linux abgeschlossen. Im Kapitel Installation wird beschrieben, wie das Dockerfile heruntergeladen und für zukünftige Updates vorbereitet werden kann.

3. Docker-Umgebungsvariablen konfigurieren

Table 1. Konfigurierbare Umgebungsvariablen vor dem ersten Serverstart über das Dockerfile
Variable Voreinstellung Beschreibung

TOMCAT_ADMIN_PASSWORD

P@ssw0rd

Passwort für den Login auf 127.0.0.1:18080/monitoring

TOMCAT_MEMORY_MIN

128

Minimal verfübarer Arbeitsspeicher in MB

TOMCAT_MEMORY_MAX

768

Maximal verfügbarer Arbeitsspeicher in MB

JAVA_OPTS

Mit JAVA_OPTS können zusätzliche Einstellungen an den Tomcat-Server übertragen werden. Beispielsweise kann die Zeitzone mit JAVA_OPTS -Duser.timezone=Europe/Berlin auf Europa/Berlin eingestellt werden.

KLAROS_VERSION

${KLAROS_VERSION:-5.7.0}

Klaros-Release-Version, die während der Installation verwendet wird. Eine Liste der verfügbaren Releases finden Sie auf der offiziellen Klaros-Testmanagement Webseite oder auf GitHub
Table 2. Veränderbare Variablen nach dem ersten Serverstart über das Dockerfile

TOMCAT_MEMORY_MIN

TOMCAT_MEMORY_MAX

JAVA_OPTS

3.1. Konfiguration über das Dockerfile

Öffne das Dockerfile unter ~/klaros-docker/ApacheDerby mit Ihrem bevorzugten Textbearbeitungsprogramm. das Dockerfile enthält eine Liste der konfigurierbaren ENV-Variablen. Weitere Informationen finden Sie in Tabelle 1.

ℹ️
 Bitte stellen Sie sicher, dass Sie das Image nach dem Ändern des Dockerfiles neu erstellen.

3.2. Konfiguration beim Serverstart

Veränderbare Variablen finden sich unter Tabelle 2. Die Umgebungsvariablen können mit dem Parameter -e geändert werden.

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

3.3. Konfiguration über eine Datei

Um die Konfigurationen über eine Datei festzulegen, kann im ApacheDerby Verzeichnis eine Textdatei erstellt werden. Modifizierbare Variablen finden Sie in Tabelle 2. Fügen Sie beim Erstellen des Containers den Parameter --env-file hinzu.

Windows Beispiel 
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 Beispiel 
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. Repository – klonen

Sobald Sie sich im gewünschten Verzeichnis befinden, können Sie das Dockerfile herunterladen
git init
git clone https://github.com/klaros-testmanagement/klaros-docker
Mit ls können Sie überprüfen, ob das Verzeichnis korrekt erstellt wurde
ls
Ausgabe: klaros-docker

4.2. Image erstellen

Das Image wird benötigt, um den Klaros-Container zu erstellen und den Server zu starten.
Windowsnutzer wechseln von Git Bash zur Powershell.

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

5. Benutzung

5.1. Eine Instanz starten

Beim Starten wird ein Docker-Container mit dem Namen „Klaros“ angelegt.

❗
 Beim Erstellen des Containers wird ein anonymes Volume erstellt. Wenn ein benanntes Volume gewünscht wird, muss -v als zusätzlicher Parameter hinzugefügt werden.
Einmalige Ausführung: Erstelle ein Klaros-Container (Anonymes Volume)
docker create --name Klaros -p 18080:18080 klaros
Einmalige Ausführung: Erstelle ein Klaros-Container (Benanntes Volume)
docker create --name Klaros -p 18080:18080 -v klaros-data:/data klaros
Sobald der Container erstellt wurde, kann der Server mit docker start hochgefahren werden
docker start -a Klaros
Um den Container im detached mode auszuführen, muss der -a Paramter entfernt werden
docker start Klaros
Details

Weitere Informationen zu den docker start Parametern finden Sie in der official Docker Documentation.

Nach dem Serverstart erscheint am Ende die Meldung „Serverstart in x ms“. Sie können jetzt mit jedem Browser Ihre IP-Adresse und Ihren Port eingeben, um auf die Klaros Webseite zuzugreifen.

Beispiel: 127.0.0.1:18080
Benutzername: admin
Passwort: admin

Eine weitere Klaros-Instanz kann dazu verwendet werden, eine neue Klaros-Version auszuprobieren oder um ein bestehendes Backup zu testen. Um eine weitere Instanz zu erstellen, muss lediglich der Containername und Port geändert werden.

Erstellen einer zweiten Klaros-Instanz mit eigener Datenbank
docker create --name Klaros2 -p 18081:18080 klaros

5.2. Instanz herunterfahren

Wenn der Container im Vordergrund gestartet wurde, können Sie den Server mit der Tastenkombination STRG + C herunterfahren (Nur für Linux möglich).

Alternativ lässt sich der Server auch über docker stop Klaros herunterfahren.

6. Erstellen, Wiederherstellen und Testen eines Backups

Backups sind mit dem Namen „backup_klaros<Datum>.tar.gz“ versehen. Falls Sie mehrere Backups am Tag erstellen, wird empfohlen beim Erstellen der Backups noch eine Uhrzeit (Stunden, Minuten und Sekunden) mitzugeben. Dazu fügen Sie in date/Get-Date %H(Stunde), %M(Minute) und %S(Sekunde) hinzu.

ℹ️
 Tritt beim Erstellen eines Backups ein Fehler auf, dann geben die Logfiles nachvollziehbare Vorgänge zu den Fehlermeldungen.
Windows Beispiel
$(Get-Date -UFormat "%y-%m-%d-%Hh-%Mm-%Ss")
Linux Beispiel
$(date '+%y-%m-%d-%H:%M:%S')
Details

Damit würde das Backup den folgenden Namen tragen:

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

Um den Backup-Pfad zu wechseln, kann der Codeabschnitt nach „-v“ geändert werden.

Windows Beispiel
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 Beispiel
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. Backup erstellen

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. Backup wiederherstellen

❗
 Vor der Wiederherstellung muss der Container heruntergefahren werden.
ℹ️
 Beachten Sie, das Datum der jeweiligen Backups anzupassen. 
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"

6.3. Backup testen

ℹ️
 Beachten Sie, das Datum der jeweiligen Backups anzupassen.

Zum Testen eines Backups kann eine zweite Klaros-Instanz erstellt werden, um darauf das Backup aufzuspielen. Die Zweite Instanz muss einmal vollständig hochgefahren werden, bevor das Backup aufgespielt werden kann.

Starten einer zweiten Klaros-Instanz
docker run --name Klaros-test -p 18081:18080 klaros
Der Server wird dann mit STRG + C oder mit docker stop Klaros-test beendet
docker stop Klaros-test
Nun wird das zu testene Backup auf das Volume von „Klaros-test“ aufgespielt und der Server gestartet
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
Wenn das Backup erfolgreich getestet wurde, kann der Server gestoppt und entfernt werden
docker stop Klaros-test
docker rm -v Klaros-test

7. Wie und wo finde ich die Logfiles?

Für die Fehlerbehebung können Logfiles erforderlich sein. Um auf Logfiles zuzugreifen, kann eine Shell direkt im Docker-Container geöffnet werden oder sie können aus dem Backup entnommen werden.

Wichtige Logs finden sich unter:

/data/catalina-base/logs

7.1. Logs über die Docker shell anzeigen

Öffnen Sie im Klaros-Container eine Shell mit docker exec, um Zugriff auf die Logs zu bekommen.

ℹ️
 Bitte beachten Sie, dass der Server beim Zugriff über die Shell gestartet sein muss und nicht heruntergefahren werden darf.
Die Logfiles können dann mit more gelesen werden
docker exec -it klaros_db /bin/sh
more /data/catalina-base/logs/catalina.2019-12-09.log

7.2. Logs aus dem Backupverzeichnis anzeigen

Windows

Windows-Nutzer können das Archivprogramm WinRAR verwenden, um .tar.gz Archive zu entpacken.

Anschließend lassen sich die Klaros-Testmanagement Logs im „logs“ Ordner von catalina-base anzeigen.

Linux
Um die Logs aus dem Backup auszulesen, lässt sich mit tar das Archive entpacken
sudo tar -xzf backup_klaros19-10-28.tar.gz

Anschließend lassen sich die Klaros-Testmanagement Logs im „logs“ Ordner von catalina-base anzeigen.

8. Update

❗
 Nach einem Update von Klaros-Testmanagement, ist das Aufspielen der vorherigen Version nicht mehr möglich. Achte ebenfalls darauf das Image nach dem Update zu aktualisieren, da sonst weiterhin die vorherige Version verwendet wird.
Bevor ein Update von Klaros-Testmanagement durchgeführt werden kann, muss ein temporärer Container mit den Volumes von Klaros erstellt werden
docker stop Klaros
docker create --name Klaros-tmp --volumes-from Klaros alpine
docker rm Klaros

8.1. Update über master branch

Klaros kann mit git pull auf die neueste Version aktualisiert werden
git pull origin master

8.2. Update über tags

Um ein Update von einer älteren auf eine neuere Version durchzuführen, wird als erstes nach neuen Updates im GitHub-Repository gesucht. Aktuelle Versionen lassen sich über git tag anzeigen. Danach kann ein lokales branch „update“ mit der gewünschten Version erstellt und gemerged werden. Alternativ kann man seinen lokalen branch auch direkt mit dem master mergen, anstatt einen zweiten branch zu erstellen.

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. Image aktualisieren

Nach dem Herunterladen des Updates aus dem GitHub-Repository wird ein neues Image erstellt und alle „dangling“ Images werden entfernt
docker stop Klaros
docker build -t klaros .
docker image prune
Nachdem das neue Image erstellt wurde, wird der Server mit den Volumes von Klaros-tmp erstellt und der temporäre Container wird anschließend entfernt. Danach kann der Server wie gewohnt gestartet werden
docker create --name Klaros --volumes-from Klaros-tmp -p 18080:18080 klaros
docker rm Klaros-tmp
docker start -a Klaros

9. Vorherige Version nutzen

❗
 Wenn bereits eine neuere Version verwendet wird, dann kann eine ältere Version nur durch das Erstellen einer weiteren Instanz oder durch eine Neuinstallation verwendet werden.

Aktuell unterstützte Versionen finden Sie unter GitHub releases.

Nachdem das Repository geklont wurde, können die Tags mit git tag aufgelistet werden und mit git checkout tags/<tag_name> -b <neuer_branch> wird ein neuer branch erstellt und ausgecheckt.

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

10. Deinstallation

Um Klaros-Testmanagement vollständig von Docker zu entfernen, muss der Container zuerst gestoppt werden, bevor der Container und das Volume entfernt werden kann.

Danach entfernen Sie das Verzeichnis ~/klaros-docker und das Image
docker stop Klaros
docker rm -v Klaros
docker rmi klaros
rm -rf ~/klaros-docker

11. Dokumentation

Informationen zum Einstieg in Klaros-Testmanagement finden Sie in unserem Tutorial und im Benutzerhandbuch. Beide sind nach erfolgreicher Anmeldung auch in der Anwendung selbst verfügbar.

Unsere Installationsdokumentation enthält die Beschreibung der Installation von Klaros-Testmanagement unter Docker für ApacheDerby-, MariaDB-, MSSQL-, MySQL- und PostgreSQL-Datenbanken.

12. FAQ

Eine technische FAQ sowie eine FAQ zu Preisen, Bestellung und Lieferung finden Sie auf unserer Webseite.

13. Lizenz

Klaros-Testmanagement für Docker ist unter den Bedingungen der MIT-Lizenz lizenziert.

Durch die Installation unserer Software über Docker stimmen Sie auch unserer Lizenzvereinbarung für Limited Use Software License Agreement zu.

14. Kontakt

Wir hoffen, dass wir Ihnen mit dieser Beschreibung einen reibungslosen Start ermöglicht haben.

Wenn Sie Fragen, Wünsche oder einfach nur Feedback geben möchten, schreiben Sie uns bitte an [email protected] oder nutzen Sie unser Forum.

15. Mitmachen

Möchten Sie uns helfen oder Verbesserungsvorschläge machen? Führen Sie diese Schritte aus, um Ihre Änderungen vorzuschlagen.

  • Erstellen Sie ein issue und beschreiben Sie Ihre Idee.

  • Fork des Repositorys

  • Erstelle einen neuen branch (git checkout -b feature/my-idea)

  • Mach deine Änderungen

  • Commite deine Änderungen (git commit -am 'Adding feature')

  • Push deine Änderungen in dein branch (git push origin feature/my-idea)

  • Erstelle ein Pull Request