//Cloudogu EcoSystem Docs

Baseline

Das Baseline-Dogu ist ein System um potenzielle Entwicklungsstände mit möglichen Elementen zu fixieren. Diese Sammlung von Elementen bildet eine Baseline und dient in der Zukunft zur schnellen Informationsgewinnung in beliebig alten Entwicklungsständen. Aktuell arbeitet das Baseline-Dogu mit dem SCM- und Nexus-Dogu zusammen. Mögliche Elemente sind zum Beispiel ein Tag eines Git-Repositorys, ein JAR-Archiv eines Maven-Releases und ein dazugehöriges Build-Log.

Web-Oberfläche

Im folgenden Abschnitt wird die Web-Oberfläche mit den einzelnen Seiten des Baseline-Dogus beschrieben. Die Startseite des Dogus sieht dabei folgendermaßen aus. Projekt Übersicht

Projekt Übersicht

Die Grundlage der Baseline bilden Git-Repositores. Konfigurierte Repositories werden in der Projektübersicht angezeigt. Diese View stellt außerdem die Anzahl der potientiellen, offenen und fixierten Baselines dar. Der Name eines Projektes verweist auf dessen Baselineübersicht.

Projekt Übersichtstabelle

Baseline Übersicht

In der Baseline Übersicht werden alle verfügbaren Baselines eines Projektes in tabellarischer Form aufgelistet. Diese bilden die Grundlage der Baseline. In der Tabelle sind der aktuelle Status, der Erstellungs-, Öffnungs-, und Fixierungszeitpunkt, der primäre Tag und der Link zur Ablage zu finden. Über einen Aktionsbutton in der letzten Spalte ist es möglich eine Baseline zu öffnen und anschließend zu fixieren. Fixierte Baselines bieten keine Aktionsmöglichkeit. Bei dem Öffnen einer Baseline werden Elemente gesammelt und deren Verweise gebündelt in einer Datei in einem eigenen Nexus-Repository gespeichert.

Baseline Übersicht

Anschließend ist es möglich diese Elemente in einer Detailansicht über den Verweis des Names zu betrachten.

Baseline Detailsicht

In dieser Ansicht sind die Elemente mit ihren Eigenschaften dargestellt. Elemente werden nach ihrem Ursprungsort gruppiert und in Form von einklappbaren Tabellen angezeigt. Eine Gruppe von Elementen wird auch Elementgruppe genannt.

Der Button "Elemente Sammeln" bietet für berechtigte Personen die Möglichkeit, das Sammeln der Elemente erneut auszuführen. Dabei werden die Elemente aller Gruppen erneut gesammelt.

Offene Baseline

In einer fixierten Baseline sind verändernde Aktionen nicht mehr möglich. Der Stand ist nun fixiert und deren Elemente können über den Verweis Ablageort begutachtet werden.

Fixierte Baseline

Das Baseline-Tool bietet die Möglichkeit an, Elementgruppen einzeln zu fixieren und zu öffnen.

Offene Elementgruppe

Jede offene Elementgruppe bietet die Aktion an, alle Elemente der Gruppe neu zu sammeln. Diese Aktion kann von berechtigte Personen über den Button "SAMMELN" durchgeführt werden.

Offene Elementgruppe

Eine berechtigte Person kann eine Elementgruppe über den Button "FIXIEREN" fixieren.

Fixierte Elementgruppe

Eine fixierte Elementgruppe verhindert, dass die Elemente dieser Gruppe verändert werden können. Beim Sammeln aller Elemente der Baseline werden fixierte Elementgruppen übersprungen. Ebenfalls wird keine separate Sammel-Aktion für die Elementgruppe mehr angeboten.

Eine berechtigte Person hat die Möglichkeit, eine fixierte Elementgruppe wieder zu öffnen. Diese Aktion kann mit dem Button "WIEDER ÖFFNEN" durchgeführt werden.

Fixierte Elementgruppe

Manuelle Ergänzungen (Elementgruppe)

Die Elementgruppe "Manuelle Ergänzungen" ist eine spezielle Elementgruppe und Teil von jedem Baseline-Projekt. Sie unterscheidet sich zu den anderen Elementgruppen darin, dass Elemente nicht automatisch gesammelt, sondern manuell hinzugefügt werden müssen. Ein weiterer Unterschied ist, dass sich die Gruppe der manuellen Elemente nicht fixieren lässt.

Manuelle Ergänzungen

Hinzufügen von Manuellen Elementen

Ein berechtigter Benutzer kann neue manuelle Elemente hinzufügen. Es gibt zwei Typen von manuellen Elementen: Dateien und Referenzen. Um neue Elemente hinzuzufügen, muss der Button "Referenzen oder Dateien hinzufügen" betätigt werden. Dies öffnet einen Dialog, welche den User beim Hinzufügen unterstützt.

Im ersten Schritt muss der Typ des Elements ausgewählt werden.

Auswahl des Element Type

Hinzufügen von Referenzen

Eine Referenz ist ein manuelles Element einer Baseline und besteht aus den folgenden Eigenschaften:

  • Eine Referenz auf eine Ressource (Link) (Notwendig)
  • Einen eindeutigen Namen für das manuelle Element (Notwendig)
  • Eine Beschreibung für das manuelle Element (Optional)

Im Dialog für Referenzen kann man nun die gewünschten Daten für die neue Referenz in das Formular eintragen.

Daten für eine Referenz hinzufügen

Nun muss der Button "Referenz hinzufügen" betätigt werden. Dadurch werden die getätigten Eingaben als Referenz zwischengespeichert. Hinweis: Die Referenz ist zu diesem Zeitpunkt noch nicht in der Baseline gespeichert.

Es gibt nun folgende Möglichkeiten:

  1. Der Dialog ermöglicht es mehrere Referenzen auf einmal hinzuzufügen. Dafür müssen die Daten für eine weitere Referenz eingeben und "Referenz hinzufügen" betätigt werden.
  2. Den "Speichern"-Button im Dialog verwenden, um alle zwischengespeicherten Referenzen in der Baseline zu speichern.

Referenz speichern

Hinzufügen von Dateien

Eine Datei ist ein manuelles Element einer Baseline und besteht aus den folgenden Eigenschaften:

  • Eine Datei eines beliebigen Typs (Notwendig)
  • Eine Beschreibung für das manuelle Element (Optional)

Im Dialog kann man den Button "Datei hochladen" verwenden, um eine Datei vom lokalen System auszuwählen. Optional kann für die Datei eine Beschreibung angegeben werden.

Daten für eine Datei hinzufügen

Nun muss der Button "Datei hinzufügen" betätigt werden. Dadurch werden die getätigten Eingaben als Datei zwischengespeichert. Hinweis: Die Datei ist zu diesem Zeitpunkt noch nicht in der Baseline gespeichert.

Es gibt nun folgende Möglichkeiten:

  1. Der Dialog ermöglicht es mehrere Dateien auf einmal hinzuzufügen. Dafür müssen die Daten für eine weitere Datei eingeben und "Datei hinzufügen" betätigt werden.
  2. Den "Speichern"-Button im Dialog verwenden, um alle zwischengespeicherten Dateien hochzuladen und in der Baseline zu speichern.

Datei speichern

Je nach Dateigröße kann das Hochladen stark variieren. Während des Hochladens ist es nicht möglich weitere manuelle Elemente hinzuzufügen. Sie sollten die Seite während des Hochladens nicht verlassen.

Datei wird hochgeladen

Nachdem das Hinzufügen der Referenzen und Dateien abgeschlossen ist, werden unsere Elemente in der Gruppe "Manuelle Ergänzungen" angezeigt.

Fixierte Elementgruppe

Löschen & Editieren von Baseline Elementen

Neben dem Hinzufügen besteht die Möglichkeit für berechtigte Personen manuelle Elemente zu ändern und vollständig zu löschen.

Für die Löschung eines manuellen Elements muss das Mülltonnen-Icon in der Spalte Aktion für das jeweilige Element betätigt werden. Darauf hin muss der Löschprozess nochmals bestätigt werden.

Das Editieren von manuellen Elementen ermöglicht es, verschiedene Eigenschaft nach ihrer Erstellung nachträglich zu ändern. Nur bestimmte Eigenschaften an manuellen Elementen lassen sich nachträglich ändern. Diese sind folgende:

Referenzen:

  • Name
  • Link
  • Beschreibung

Datei:

  • Beschreibung

Änderbare Eigenschaften (Zelle) von manuellen Elementen werden in der Tabelle mit einem schwarzen Dreieck in der unteren rechten Ecke einer Zelle markiert. Die mit einem Dreieck markierten Zellen können per Doppelklick oder unter Focus mit der Bestätigung der Eingabetaste editiert werden. Dafür versetzt sich die Zelle in einen Bearbeitungsmodus. Im Bearbeitungsmodus kann der Inhalt der Zelle angepasst werden. Durch Bestätigung der Eingabetaste wird der neu eingegebene Wert gespeichert.

Bearbeitungsmodus für manuelle Elemente

Hinweis: Der Inhalt einiger Eigenschaften wird verifiziert und invalide Wert können nicht gespeichert werden. Ein invalider Wert wird durch eine rote Einfärbung der Zelle kenntlich gemacht. Generell gelten die folgenden Einschränkungen:

  1. Der Name einer Referenzen darf nicht leer sein.
  2. Der Name einer Referenzen darf sich nicht mit dem Namen eines anderen manuellen Elements überschneiden.
  3. Der Link einer Referenzen muss eine valide URL sein.

Bearbeitungsmodus mit invaliden Wert für manuelle Elemente

Konfiguration der Projekte

In einer JSON-Datei können verschiedene Einstellungen für Projekte, zu denen Baselines gehören, vorgenommen werden. Der Ablageort dieser Projektkonfigurationsdatei ist konfigurierbar (siehe Konfiguration des Baseline-Dogus)

Der Admin-Benutzer ist berechtigt, die Projektkonfiguration auf der Projektseite im Baseline-Tool zu ändern, indem er auf die Schaltfläche Projekte verwalten klickt.

Die Konfiguration der einzelnen Projekte erfolgt als Array.

Beispiel einer vollständigen Projektkonfiguration mit zwei Projekten

Das folgende Beispiel zeigt eine vollständige Projektkonfiguration mit den zwei Projekten petclinic und cas.

Das Projekt petclinic stellt eine Projektkonfiguration mit allen optionalen Attributen dar. In diesem Projekt sind für das Sammeln von Baseline-Elementen zusätzliche SCM-Repositorys, ein Nexus-Artefakt und eine Jenkins-Build-Logdatei konfiguriert.

Das Projekt cas gibt eine simple Projektkonfiguration wieder, in dem eine Baseline jeweils nur aus einem einzigen SCM-Tag besteht.

[
  {
    "id": "petclinic",
    "scm_url": "https://baseline.cloudogu.net/scm",
    "full_qualified_repository_name": "baselineTest/spring-petclinic",
    "additional_repository_names": [
      "baselineTest/summer-petclinic",
      "baselineTest/fall-petclinic",
      "baselineTest/winter-petclinic"
    ],
    "tag_regex": "^.*",
    "nexus": {
      "url": "https://baseline.cloudogu.net/nexus",
      "nexus_artefacts": [
        {
          "repository": "maven-releases",
          "name": "Petclinic JAR",
          "location": "org/springframework/samples/spring-petclinic/${tag}/spring-petclinic-${tag}.jar"
        }
      ]
    },
    "jenkins": {
      "nexus_url": "https://baseline.cloudogu.net/nexus",
      "repository": "maven-releases"
    },
    "app_version": "0.5.0-1"
  },
  {
    "id": "cas",
    "scm_url": "https://baseline.cloudogu.net/scm",
    "full_qualified_repository_name": "baselineTest/cas",
    "tag_regex": "^.*",
    "app_version": "0.5.0-1"
  }
]

Konfiguration eines einzelnen Projekts

The individual configuration options of a single project are described in more detail below.

Konfiguration der Projekt-ID

Jedes Projekt hat eine eindeutige ID. Die ID des Projekts entspricht gleichzeitig dem Namen des Projekts. Alle konfigurierten Projekte werden in der Projekte-Übersicht angezeigt.

  • Attribut-Key: id
  • Datentyp: String
  • Beispiel: "id": "petclinic"
Konfiguration der SCM-Repositorys

Für jedes Projekt müssen Einstellungen für den Zugriff auf den SCM-Manager konfiguriert werden. Potenzielle Baselines werden im SCM-Manager ermittelt.

Konfiguration der SCM-URL

In der Projektkonfigurationsdatei muss die URL zu dem SCM-Manager, in dem die konfigurierten Repositorys zu finden sind, angegeben werden.

  • Attribut-Key: scm-url
  • Datentyp: String
  • Beispiel: "scm_url": "https://ecosystem.cloudogu.com/scm"
Konfiguration des SCM-Repositorys mit den potenziellen Baselines

In der Projektkonfigurationsdatei muss ein SCM-Repository angegeben werden, in dem die SCM-Tags der potenziellen Baselines zu finden sind. Bei der Ermittlung der potenziellen Baselines wird dieses Repository nach den Tags durchsucht, die dem konfigurierten Tag-Pattern entsprechen.

Beim Sammeln der Elemente einer Baseline wird der entsprechende SCM-Tag mit eingesammelt und in der Baseline-Detailansicht unter SCM-Manager angezeigt.

Das SCM-Repository muss mit seinem Namespace angegeben werden: <namespace>/<repository name>.

  • Attribut-Key: full_qualified_repository_name
  • Datentyp: String
  • Beispiel: full_qualified_repository_name": "demo/spring-petclinic"
Konfiguration von weiteren SCM-Repositorys für das Sammeln von SCM-Tags

Für das Sammeln von Baseline-Elementen ist es optional möglich, weitere SCM-Repositorys anzugeben. Beim Sammeln der Baseline-Elemente werden diese Repositorys dann mit berücksichtigt. Dabei wird in diesem Repositorys nach SCM-Tags mit gleichem Namen wie die Baseline gesucht. Die Tags, die aus den hier konfigurierten Repositorys gesammelt werden, werden in der Baseline-Detailansicht unter SCM-Manager angezeigt.

Die SCM-Repositorys müssen jeweils mit Namespace angegeben werden: <namespace>/<repository name>.

  • Attribut-Key: additional_repository_names
  • Datentyp: Array mit Strings
  • Optional
  • Beispiel:
"additional_repository_names": [
  "demo/spring-petclinic-clone",
  "demo/spring-petclinic-additionals"
]
Konfiguration des Patterns für die SCM-Tags

In der Projektkonfigurationsdatei muss ein Pattern (regulärer Ausdruck) für die zu berücksichtigen SCM-Tags angegeben werden. Bei der Ermittlung der potenziellen Baselines werden nur diejenigen Tags berücksichtigt, die dem konfigurierten Pattern entsprechen.

  • Attribut-Key:
  • Datentyp: String
  • Beispiel: "tag_regex": "^.*"
Konfiguration zum Sammeln von Artefakten aus Nexus

Für das Sammeln von weiteren Baseline-Elementen ist es optional möglich, ein Nexus mit einem oder mehreren zu sammelnden Artefakten zu konfigurieren. Beim Sammeln der Baseline-Elemente werden diese Artefakte dann mit berücksichtigt. Die hier gesammelten Artefakte werden in der Baseline-Detailansicht unter Nexus angezeigt.

Die Konfiguration erfolgt unter dem Punkt "nexus": { ... }

  • Attribut-Key: nexus
  • Datentyp: Struct
  • Optional
  • Beispiel:
"nexus": {
  "url": "https://baseline.cloudogu.net/nexus",
  "nexus_artefacts": [
    {
      "repository": "maven-releases",
      "name": "Petclinic JAR",
      "location": "org/springframework/samples/spring-petclinic/${tag}/spring-petclinic-${tag}.jar"
    }
  ]
}
Konfiguration der Nexus-URL

Wenn Artefakte aus Nexus gesammelt werden sollen, muss in dem Nexus-Struct die URL zu der Nexus-Instanz konfiguriert werden.

  • Attribut-Key: url
  • Datentyp: String
  • Beispiel: "url": "https://baseline.cloudogu.net/nexus"
Konfiguration von Nexus-Artefakten

Es können ein oder mehrere Artefakte angegeben werden, die aus Nexus gesammelt werden. Die Konfiguration der Artefakte erfolgt dabei als ein Array von Nexus-Artefakt-Objekten.

  • Attribut-Key: nexus_artefacts
  • Datentyp: Array
  • Beispiel:
"nexus_artefacts": [
  {
    "repository": "maven-releases",
    "name": "Petclinic JAR",
    "location": "org/springframework/samples/spring-petclinic/${tag}/spring-petclinic-${tag}.jar"
  }
]
Konfiguration eines Nexus-Artefakts

Für die Konfiguration eines Nexus-Artefakts müssen das Repository, der Name und der Ort des Artefakts angegeben des werden.

Konfiguration des Artefakt-Repositorys

Das Artefakt-Repository gibt das Repository an, in dem nach dem bestimmten Artefakt gesucht wird.

  • Attribut-Key: repository
  • Datentyp: String
  • Beispiel: "repository": "maven-releases"
Konfiguration des Artefakt-Namens

Der Artefakt-Name gibt den Namen an, unter dem das Artefakt an der Baseline gespeichert wird.

  • Attribut-Key: name
  • Datentyp: String
  • Beispiel: "name": "Petclinic JAR"
Konfiguration des Artefakt-Ortes

Der Ort gibt den Namen an, unter dem das zu sammelnde Artefakt gefunden werden kann. Die Lokation kann andere Werte aus der Projektkonfiguration als Platzhalter verwenden.

  • Attribut-Key: location
  • Datentyp: String
  • Beispiel: "location": "org/springframework/samples/spring-petclinic/${tag}/spring-petclinic-${tag}.jar"
Konfiguration zum Sammeln einer Jenkins-Build-Logdatei

Für das Sammeln von weiteren Baseline-Elementen ist es optional möglich, das Sammeln einer Jenkins-Build-Logdatei zu konfigurieren. Die hier gesammelte Jenkins-Build-Logdatei wird in der Baseline-Detailansicht unter Jenkins angezeigt.

Konkret wird hier beim Sammeln der Baseline-Elemente im unter jenkins konfigurierten Nexus-Repository nach einer Jenkins-Build-Logdatei (maven.extension=log) gesucht, die anhand der Revision (Commit-ID) des Baseline-Tags ermittelt wird. Die Commit-ID ist der classifier der Maven-Dependency.

Die Konfiguration erfolgt unter dem Punkt "jenkins": { ... }

  • Attribut-Key: jenkins
  • Datentyp: Struct
  • Optional
  • Beispiel:
"jenkins": {
  "nexus_url": "https://baseline.cloudogu.net/nexus",
  "repository": "maven-releases"
},
Konfiguration eines Nexus-Repositorys für das Sammeln der Jenkins-Build-Logdatei

Wenn eine Jenkins-Build-Logdatei aus Nexus gesammelt werden soll, müssen in dem Jenkins-Struct die URL zu der Nexus-Instanz und das Repository konfiguriert werden.

Konfiguration der Nexus-URL

Die Nexus-URL gibt die URL zum Nexus an, in dem sich das Repository mit den Jenkins-Build-Logdateien befindet.

  • Attribut-Key: nexus_url
  • Datentyp: String
  • Beispiel: "nexus_url": "https://baseline.cloudogu.net/nexus"
Konfiguration des Repositorys

Das Repository gibt das Repository an, in dem nach der Jenkins-Build-Logdatei gesucht wird.

  • Attribut-Key: repository
  • Datentyp: String
  • Beispiel: "repository": "maven-releases"
App-Version

Im Textfeld für das Verwalten von Projekten wird pro Projekt auch ein Feld app_version angezeigt. Dieser Wert wird vom System automatisch geschrieben und ist lediglich für interne, technische Details erforderlich und kann auch nicht verändert werden.

Berechtigungen

Damit ein Benutzer das Baseline-Dogu öffnen und dort Daten lesen und bearbeiten kann, muss er über die entsprechenden Berechtigungen verfügen. Dieser Artikel beschreibt, welche Benutzergruppen es gibt, wie sich diese unterscheiden und wie sie konfiguriert werden können.

Mapping der Gruppen aus dem User-Management

Das Anlegen der Gruppen für das Baseline-Dogu erfolgt im User Management. Ebenso finden hier die Gruppenzuordnungen der einzelnen Benutzer statt.

Ein entsprechendes Mapping der Gruppen aus dem User Management erfolgt über die Konfiguration des Baseline Dogus. (s. Konfiguration des Dogus).

Benutzergruppen

Es gibt die folgenden drei Berechtigungsgruppen für das Baseline-Dogu:

  • Baseline-Leser
  • Baseline-Bearbeiter
  • Baseline-Admin

Die einzelnen Berechtigungsgruppen bauen aufeinander auf. Dies bedeutet:

  • Baseline-Bearbeiter und Baseline-Admins haben die Berechtigungen des Baseline-Lesers.
  • Baseline-Admins haben die Berechtigungen des Baseline-Bearbeiters.
Baseline-Leser

Der Baseline-Leser hat – wie der Name schon sagt – das Recht, die Informationen aus dem Baseline-Dogu zu lesen. Er ist nicht berechtigt schreibende Aktionen, die Daten verändern, durchzuführen.

Wenn keine Gruppe zum Lesen des Baseline Dogus konfiguriert ist, darf jeder im CAS existierende Nutzer das Baseline-Dogu Öffnen und die Informationen zu den Baselines lesen.

Wenn jedoch explizit eine Gruppe für das Lesen des Baseline-Dogus konfiguriert ist, muss ein Benutzer in mindestens einer der drei existierenden Baseline-Gruppen sein, um das Baseline-Dogu generell öffnen zu können.

Baseline-Bearbeiter

Der Baseline-Bearbeiter darf schreibende, Daten verändernde Aktionen durchführen. Unter anderem kann der Baseline-Bearbeiter eine Baseline öffnen, eine Baseline fixieren und Artefakte erneut sammeln.

Der Baseline-Bearbeiter kann eine Baseline jedoch nicht erneut öffnen und darf keine Änderungen an der Konfiguration vornehmen.

Folgende Aktionen darf der Baseline-Bearbeiter ausführen:

  • Baseline öffnen
  • Baseline fixieren
  • Artefakte einer Baseline erneut sammeln
  • Element-Gruppe fixieren
  • Element-Gruppe wieder öffnen
  • Manuelle Elemente hinzufügen und vorhandene Elemente bearbeiten und löschen
Baseline-Admin

Der Baseline-Admin darf gegenüber dem Baseline-Bearbeiter zusätzliche Aktionen ausführen. Hierzu gehören das erneute Öffnen einer Baseline sowie das Konfigurieren des Baseline Dogus.

Folgende Aktionen darf der Baseline-Admin ausführen:

  • Alle Aktionen des Baseline-Bearbeiters
  • Baseline erneut öffnen
  • Projektkonfiguration ändern
  • Einstellungen des Baseline-Tools einsehen