Migration von Trac zu JIRA

Einführung von Atlassians Confluence, FishEye und JIRA

In diesem Artikel geht es um die Einführung, also Installation und Konfiguration, der Produkte JIRA, FishEye und Confluence von der Firma Atlassian in einer ursprünglich rein Trac-basierten Umgebung.

Als nötiges Hintergrundwissen geht dieser Artikel davon aus, dass die jeweiligen Hersteller-Guides bereits bekannt sind oder bei Fragen zu Rate gezogen werden können. Es werden nicht alle Funktionen und Features der Produkte im einzelnen vorgestellt oder erklärt (etwa: Was ist ein Crowd-Server? oder Wie deaktiviere ich den Benutzer-Signup?).

Am Ende des Artikels findet sich eine kleine Linksammlung zu den offiziellen Dokumentationen.

Installation

Für eine saubere Installation empfiehlt es sich, die Anwendungen von einander getrennt zu installieren. Damit ist gemeint, dass jede Anwendung ihren eigenen Systemaccount, Tomcatinstanz und eventuell sogar Speicherplatz erhält. Darüber hinaus benötigen alle drei Produkte im Gegensatz zu Trac eine Datenbank im Hintergrund; dabei lassen sich alle gängigen Hersteller wieder finden.

Alle drei Produkte lassen sich als Standalone oder als WAR herunterladen und installieren. Während die WAR -Variante nur in einen vorhandenen Tomcat deployt wird, ist die Standalone-Variante eine fertig konfigurierte Einheit, die auch entsprechend korrekt konfiguriert ist. Aus mehreren Gründen ist die Standalone-Variante vorzuziehen: Nebst der ausdrücklichen Empfehlung Atlassians ist sie einfacher als Service zu managen und bringt eingebaute Performance-Tunings des Herstellers mit. Selbstverständlich ist dabei darauf zu achten, das die Tomcatinstanzen unterschiedliche Ports belegen müssen.

Leider ist die Qualität (oder besser: der Funktions- und Konfigurationsumfang) der Standalone-Versionen nicht bei allen Produkten überall gleich; JIRA ist dabei am Besten und quasi vollständig.

Für diesen Beitrag werden die Produkte jeweils in die drei Verzeichnisse /opt/confluence, /opt/fisheye und /opt/jira installiert. Dies wurde unter einem gängigen Linux durchgeführt, lässt sich aber prinzipiell auf alle anderen Systeme adaptieren.

Hinweis: In der Evaluationsversion erlauben alle Produkte die Verwendung einer Embedded HSQLDB. Sobald man eine Lizenz erworben und aktiviert hat, ist dies nicht mehr möglich.

JIRA

Praktischerweise wird JIRA in einem selbstausführenden Installer zur Verfügung gestellt. Also sudo gestartet, sollte man hier den empfohlenen Weg nehmen und JIRA als Service mit eigenem Benutzer installieren. Da der Installer selbstständig einen Benutzer jira anlegen wird, sollte dieser nicht vorher schon existieren. Ist bereits einer vorhanden, legt der Installer jira1 an, inkl. einem gleichlautenden Service.

Danach ist JIRA installiert und muss via Web konfiguriert werden. Für die produktive Installation bedeutet dies beispielsweise die Konfiguration einer externen Datenbankanbindung.

Hinweis: Sofern der Administratorzugang mit einem Benutzer aus dem späteren Trac-Import matchen soll, sollte der Benutzername gleich heißen.

Hinweis: Sollen mehrere Tomcats auf einer Maschine laufen, müssen die Ports entsprechend verändert werden. Die JIRA-Tomcat-Konfiguration ist unter conf/server.xml zu finden. Dort findet sich auch ein auskommentierter Connector für AJP.

Es empfiehlt sich, den Remote- und API-Zugriff sofort zu aktivieren, da dieser in der Regel immer gebraucht wird (etwa für Eclipse Mylyn).

Tipp: Falls die Benutzerkonten zwischen JIRA, Confluence und FishEye synchronisiert werden sollen (und das ist sicher zu empfehlen): Dieses Feature heißt bei Atlassian Crowd und ist in allen Produkten implementiert. Hierbei spielt JIRA dann den Crowd-Server, d.h. es stellt die Konten und Passwörter zur Verfügung. Confluence und FishEye werden später nur passiv gespiegelt. Es sind jedoch auch andere Szenarien möglich, dazu sollte dann die jeweilige Dokumentation zu Rate gezogen werden.

FishEye

FishEye wird im Gegensatz zu JIRA nicht mit einem Installer ausgeliefert. Das entpackte Archiv beinhaltet nur die Applikation. Da der Standardport von FishEye 8060 ist und sich damit selten mit anderen Diensten überschneidet, kann man dies so stehen lassen.

Da FishEye von sich aus kein Service-Script mitliefert, muss man das selber beisteuern. Außerdem sollte man sich auch hier um einen eigenen Benutzer kümmern (etwa sinnigerweise fisheye).

#!/bin/bash
# Fisheye startup script
# chkconfig: 345 90 90
# description: Atlassian FishEye
# original found at: http://jarrod.spiga.id.au/?p=35

FISHEYE_USER=fisheye
FISHEYE_HOME=/opt/fisheye/fisheye/bin
start() {
        echo "Starting FishEye: "
        if [ "x$USER" != "x$FISHEYE_USER" ]; then
          su - $FISHEYE_USER -c "$FISHEYE_HOME/fisheyectl.sh start"
        else
          $FISHEYE_HOME/fisheyectl.sh start
        fi
        echo "done."
}
stop() {
        echo "Shutting down FishEye: "
        if [ "x$USER" != "x$FISHEYE_USER" ]; then
          su - $FISHEYE_USER -c "$FISHEYE_HOME/fisheyectl.sh stop"
        else
          $FISHEYE_HOME/fisheyectl.sh stop
        fi
        echo "done."
}

case "$1" in
  start)
        start
        ;;
  stop)
        stop
        ;;
  restart)
        stop
        sleep 10
        start
        ;;
  *)
        echo "Usage: $0 {start¦stop¦restart}"
esac

exit 0

FishEye wird per Default in eine HSQLDB installiert. Im Gegensatz zu JIRA kann man nicht bereits zu Beginn eine alternative Datenbank auswählen. Dafür kann Fisheye jedoch einfach on the fly via „Administration / Database“ in eine externe Datenbank migriert werden. Falls die Crowd-Funktionalität von JIRA verwendet werden soll, muss in der Administration der JIRA-Server als Application-Link angelegt werden. Anschließend kann man die Benutzer synchronisieren (passiert automatisch alle 60 Minuten) und das lokale Registrieren abschalten.

Hinweis: Mit dem FishEye-Administrator-Passwort kommt man immer in das Admin-Backend zurück. Dennoch empfehlt es sich, einen Login in einem separaten Browser (oder einfach im Inkognito/Private-Modus) auszuprobieren.

Per Default werden Benutzer, die in der Gruppe jira-administrators sind, auch automatisch FishEye-Administratoren. Erst nach Abschluss dieser Feinheiten lohnt sich das Anlegen von Repositories.

Hinweis: Lässt man die alte Trac-Installation noch weiter laufen, so kann man in den Eigenschaften eines FishEye-Repositories einen Linker definieren, damit in Commits erscheinenden Ticket-Referenzen (zum Beispiel #123) auf Trac verweisen können (ein reguläres Muster wäre: #(d+)). Prinzipiell kann man auch einen Link auf FishEye selber erzeugen, das funktioniert natürlich nur, wenn keine Tickets aufgrund von Projekt-Splittung verschoben wurden.

Nach erfolgtem Anlegen und Indizieren des Repositorys (oder sogar mehrerer Repositories) sollte der Übersichtlichkeit wegen Projekte Projekte angelegt werden — idealerweise in der gleichen Struktur wie unter JIRA. FishEye-Projekte sind dabei als Filter zu verstehen: Ausgehend von einem oder mehreren Repositories lassen sich Teile davon als Projekt zusammenführen. Dies vereinfacht nicht nur die Navigation und Strukturierung, sondern ermöglicht auch die Erzeugung und Darstellung projektspezifischer Statistiken in Form von Kennzahlen und Grafiken.

Anschließend kann man mit den Application-Links dafür sorgen, dass erstens FishEye Kenntnis davon hat, dass ein ein bestimmtes Projekt einer JIRA-Installation in den Changeset-Kommentaren verlinkbar ist und zweitens der entsprechenden JIRA-Installation eine Backreferenz auf diese FishEye-Quelle geben. Mit dieser Konfiguration werden also Commits mit einem Verweis auf ein Ticket („… PROJECTKEY-123…“) automatisch auf JIRA verlinkt und gleichzeitig im JIRA-Vorgang als Aktivität aufgelistet.

Confluence

Wie FishEye bietet auch Confluence nur ein entpacktes Verzeichnis mit der Anwendung an. Auch hier muss man sich um ein Service-Script und einen Benutzer selber kümmern.
Und auch hier sollte man nach erfolgter Installation die Authentifizerung auf JIRA umstellen, um das Accountmanagement mittels Crowd zu minimieren. Dafür muss man eine Referenz auf JIRA anlegen. Eventuell ist es auch nötig, eine zusätzliche Referenz seitens JIRA auf Confluence (erlaubte Abfrage der Konten) anzulegen.

#!/bin/sh -e
# Confluence startup script
#chkconfig: 2345 80 05
#description: Confluence
#original found at: http://confluence.atlassian.com/display/DOC/Start+Confluence+automatically+on+Linux+and+UNIX

# Define some variables
# Name of app ( JIRA, Confluence, etc )
APP=confluence
# Name of the user to run as
USER=confluence
# Location of application's bin directory
CATALINA_HOME=/usr/local/confluence/current
# Location of Java JDK
export JAVA_HOME=/usr/lib/jvm/java-6-sun

case "$1" in
  # Start command
  start)
    echo "Starting $APP"
    /bin/su -m $USER -c "$CATALINA_HOME/bin/startup.sh &> /dev/null"
    ;;
  # Stop command
  stop)
    echo "Stopping $APP"
    /bin/su -m $USER -c "$CATALINA_HOME/bin/shutdown.sh &> /dev/null"
    echo "$APP stopped successfully"
    ;;
   # Restart command
   restart)
        $0 stop
        sleep 5
        $0 start
        ;;
  *)
    echo "Usage: /etc/init.d/$APP {start¦restart¦stop}"
    exit 1
    ;;
esac

exit 0

Wichtiger Hinweis: Es ist dringendst zu empfehlen, vor dem Switch auf den JIRA-Crowd-Server dem eigenen Konto (in JIRA!) die neu zu erstellenden Benutzergruppe confluence-administrators hinzuzufügen — ansonsten sperrt man sich sofort aus. Hat man den Abgleichtimer auf eine Stunde gestellt und will – für Confluence – nicht von vorne anfangen, ist man eine Stunde bis zur nächsten Synchronisation merkbefreit.

Von Trac zu JIRA

Upgrade auf Trac 0.12

Das Importwerkzeug von JIRA ist nur mit Trac-Export-Daten kompatibel, die aus einer 0.12-Installation heraus erstellt wurden. (Falls bereits eine neuere Installation als 0.11 verwendet wird, kann dieser Abschnitt übersprungen werden.)

Das macht sich unter anderem daran bemerkbar, das zwar der Import prinzipiell funktioniert, aber beispielsweise alle Zeiten/Zeitstempel falsch sind (01. Januar 1970). Dieser Umstand wird durch eine Änderung der internen Speicherung von Timestamps in Trac geschuldet (0.11 speichert in Sekunden, 0.12 jedoch in Mikrosekunden).

Daher war es zunächst erforderlich, die vorhandene Trac-Installation mittels Upgrade auf 0.12 zu aktualisieren. Je nach Installation ist ein Upgrade einfach oder eher umständlich.

Hinweis: Es kann durchaus sinnvoll sein, dass man seine bisherige Trac-Installation unverändert lassen will. Dies ist relativ einfach zu bewerkstelligen. Auf einer separaten Maschine (dafür eignet sich auch ein schnell aufgezogenes Debian in der VM) wird Trac 0.12 etwa via apt-get installiert.Danach wird ein Trac-Repository konfiguriert und anschließend das existierende Repository 1:1 herüberkopiert.

Die anschließenden Befehle trac-admin upgrade und trac-admin wiki upgrade hiefen sowohl die Trac-Datenbank als auch die Wikiseiten auf die neue Version – fertig!

Export von Trac

Die Trac-Daten werden wie folgt exportiert: Die Tickets liegen alle in einer Datenbank im Repository, die Attachments liegen als Dateistruktur ebenfalls im Repository. Man wechselt in das Verzeichnis des Trac-Repositorys und packt alles zusammen in ein Zip-Archiv.

Import in JIRA

Im Import-Assistenten wählt man Trac und danach das zuvor erstellte Zip-Archiv. Je nach Größe kann es erforderlich sein, dass man in der JIRA-Administration das Upload-Limit für Dateien (kurzfristig) erhöhen muss. Der Assistent entpackt das Archiv und analysiert die Strukturen. Sofern man keine Besonderheiten hat, kann man die Schritte alle absegnen. Eventuelle CustomFields sollten ebenfalls als solche auch in JIRA eingefügt werden.

Das „No Priority“-Issue

Beim Import der Ticket-Daten wird u.U. das Feld Priority nicht korrekt übernommen, weil beispielsweise der Importer Daten falsch erkannt hat oder man bei der Konfiguration des Importers einen Fehler gemacht hat. Am Beispiel der „prioritätslosen Tickets“ soll ein Lösungsweg veranschaulicht werden.

Beim Import kann es passieren, dass das Trac-Feld Status=“Blocker“ nicht korrekt erkannt wird. Das hat als Auswirkung, dass beim Editieren eines Tickets automatisch die erstbeste Priorität seitens JIRA verwendet wird. Da dies 1 => Blocker ist, kann das unerwartete Nebeneffekte haben.

Prinzipiell ist so etwas aber kein großer Aufwand, da JIRA ein sehr ausgeklügeltes und vor allem funktionierendes Mehrfachbearbeitungsmanagement mitliefert. Über „Vorgänge / Suchen / Erweitert“ kann man mittes JQL eine sehr spezifische Abfrage nach Vorgängen machen. Über jede getätigte Abfrage lässt sich über den Button „Tools“ in der rechten, oberen Ecke eine Mehrfachbearbeitung starten.

Hinweis: Da der Name des Trac-Felds „Priority“ mit dem JIRA-Feld „Priority“ konkurriert, hat der Importer ein generisches Feld (cf-xxxx) anlegt. Nicht verwirren lassen!

Über die Abfrage „status = Reopened and priority is empty and cf[xxxxx] = Blocker“ lassen sich beispielsweise alle „prioritätslosen“ Tickets abfragen, die aus Trac mit Blocker-Priorität kommen“. Über die Mehrfachbearbeitung setzt man dann die Priorität auf „Blocker“. Das gleiche für alle anderen Prioritäten.

Das „Reopened Issues“-Issue

Beim Import der Ticket-Daten wurden alle bereits geschlossenen und „resolved“ Tickets mit dem Status „Reopened“ eingeladen. Auch hierfür eignet sich die Mehrfachbearbeitung.

Hinweis: Der Standard JIRA-Workflow der Mehrfachbearbeitung erfordert beim Schließen eines Vorgangs die Angabe einer (neuen) Resolution / Lösung. Daher ist es wie bei „No-Priority“ empfehlenswert, die Abfrage gruppiert nach eine Trac-Resolution zu machen. Ansonsten verliert man die originale Resolution.

Von Trac nach Confluence

Export von Trac

Die Daten der Wiki-Seiten liegen als Dateistruktur im Trac-Repository. Da der Export bereits unter weiter oben „Von Trac nach JIRA“ erfolgt ist, hat man die Wiki-Daten bereits vorliegen.

Import in Confluence

Für den Import der Daten steht ein universelles Java-Programm zur Verfügung (ist in der Confluence-Administration unter Import zu finden). Damit lassen sich die Trac-Daten (aber auch noch eine ganze Reihe anderer Formate/Anwendungen) in das Confluence-Schema importieren. Das Programm ist etwas unglücklich designed und die Steuerung ist an einigen Punkten etwas unsauber implementiert — sofern man jedoch einiges beachtet, funktioniert alles einwandfrei.

Zunächst wählt man in der Liste „trac“ aus. Danach wählt man den Ordner der Attachments aus, was voraussetzt, das man das Trac-Repository auf dem Rechner zur Verfügung stehen hat, auf welchem der Importer ausgeführt wird. Anschließend wählt man die Wiki-Seiten aus. Hierbei ist anzumerken, dass der Importer den kompletten, absoluten Pfad der Dateien übernimmt! Das ist äußerst unschön, weil man zwar in Confluence später zwar einzelne, aber nicht mehrere Seiten gleichzeitig verschieben kann. Unter Umständen kann es sinnvoll sein, die Wiki-Seiten für diesen Import kurzfristig auf einem /-Level anzulegen. Ein Unding ohne Gleichen (Tipps an dieser Stelle gerne willkommen und werden ergänzt). Nach der Angabe der Confluence-Server-Angaben werden die Daten importiert.

Hinweis: Die externe API muss in Confluence selbstverständlich aktiviert sein.

Linksammlung

Stets beachten: Die Dokumentationen beziehen sich auf eine bestimmte (meist zuletzt veröffentlichte Version). Eventuell muss ein entsprechender Deeplink zu einer konkreten, älteren Version angewählt werden.

Dieser Beitrag wurde auch unter dem privaten Blog des Autors veröffentlicht.

Schreibe einen Kommentar