Einführung von Atlassians Confluence, FishEye und JIRA

In diesem Artikel geht es um die Installation und Konfiguration von Atlassians JIRA, FishEye und Confluence in einer ursprünglich rein Trac-basierten Umgebung.

Ich gehe davon aus, dass die Hersteller-Guides bereits bekannt sind oder bei Fragen zu Rate gezogen werden. Es werden nicht alle Funktionen und Features der Produkte im einzelnen vorgestellt oder erklärt (etwa: Was ist ein Crowd-Server? oder Wie stelle ich den Benutzer-Signup aus?).

Installationen

Für eine saubere Installation empfiehlt es sich, die Anwendungen von einander getrennt zu installieren.

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: Service-Able, besseres Tuning im Performance-Problemfall.

Leider ist die Qualität der Standalone-Versionen nicht überall gleich; JIRA ist dabei am Besten und quasi vollständig.

Für diesen Beitrag installieren wir die Produkte jeweils in die drei Verzeichnisse /opt/confluence, /opt/fisheye und /opt/jira. Und natürlich unter Linux.

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 eine externe Datenbankanbindung.

Hinweis 1
Sofern der Administratorzugang mit einem Benutzer aus dem späteren Trac-Import matchen soll, sollte der Benutzername gleich heißen.
Hinweis 2
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).

Falls die Benutzerkonten zwischen JIRA, Confluence und FishEye synchronisiert werden sollen (und das ist sicher zu empfehlen): Das 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.

FishEye

FishEye wird im Gegensatz zu JIRA nicht mit einem Installer ausgeliefert. Das Archiv entpackt hinterlässt 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 muss man sich auch selber um einen Benutzer (etwa sinnigerweise fisheye) kümmern.

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 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 (etwa automatisch jede Stunde) und das lokale Registrieren abschalten.

Hinweis
Mit dem FishEye-Administrator-Passwort kommt man immer in die Admin-Backend zurück. Dennoch empfehle ich, einen Login in einem separaten Browser (oder einfach im Inkognito-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 (#123) auf Trac verweisen können (reguläres Muster: #(\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 der Repositories) sollte der Übersichtlichkeit wegen Projekte anlegen – idealerweise in der gleichen Struktur wie unter JIRA. Anschließend kann man mit den Application-Links dafür sorgen, dass erstens FishEye weißt, 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 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 an. Auch hier muss man sich um ein Service-Script und einen Benutzer selber kümmern.

Auch hier sollte man nach erfolgter Installation die Authentifizerung auf JIRA umstellen. 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.

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 merkbefreit.

Von Trac nach 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.

Die vorhandene Trac-Installation lief leider noch in der Vorgängerversion 0.11. 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 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 vom Trac-Repository 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 wurde das Feld Priority nicht korrekt übernommen. Das hat die Auswirkung, dass beim Editieren eines Tickets automatisch die erstbeste Priorität seitens JIRA verwendet wird. Und das ist 1 => Blocker. Etwas unschön.

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.

Ü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 Workflow erfordert beim Schließen eines Vorgangs die Angabe einer Resolution. 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 “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 ohnegleichens.

Nach der Angabe der Confluence-Server-Angaben werden die Daten importiert. Hinweis: Die externe API muss in Confluence selbstverständlich aktiviert sein.

Bonus

Hudson/Jenkins-Integration

Zwar bietet Atlassian natürlich eine perfekte Integration in und mit ihrem eigenen Buildserver Bamboo an, dies ist aber nicht zwingend erforderlich. In der Regel reicht es aus, wenn man im Ticket automatisch/sofort erkennen kann, mit welchem Build ein Ticket bzw. ein entsprechender Changeset aufgenommen wurde. Dafür gibt es das Jenkins JIRA-Plugin.

Zuallererst muss in der globalen Konfiguration von Jenkins die JIRA-Installation konfiguriert werden. In den meisten Fällen muss dafür ein Benutzer angegeben werden: Will man es schön und sauber, dann legt man unter JIRA einen eigenen Buildserver-Benutzer an (etwa mit schönem Avatar?) und trägt dessen Zugangsdaten (generisches, langes Passwort?) in der Jenkins-Konfiguration ein.

Danach kann man im entsprechenden Jenkins-Job das JIRA-Plugin aktivieren und weiteres Tuning machen.

Mit dieser Konfiguration wird ein Build als weitere Aktivität in einem JIRA-Vorgang auftauchen.

Hinweis in eigener Sache Dieser Artikel ist auch im Blog der Herrmann & Lenz Services GmbH veröffentlicht worden.