1. Einleitung
CaaS Connect stellt die redaktionellen Daten von FirstSpirit über ein einheitliches JSON-basiertes Datenformat beliebigen Endpunkten bereit. Die Verwendung des CaaS Connect-Moduls ab Version 3 und der CaaS-Plattform reduziert den Konfigurations- und Administrationsaufwand im FirstSpirit-Projekt für die Auslieferungsschicht erheblich.
|
Content as a Service wird im Folgenden als CaaS abgekürzt. |
1.1. Technische Voraussetzungen
Neben der FirstSpirit Version 5.2.210710, setzt das Modul den Zugriff auf die CaaS-Plattform voraus. Hierfür muss ein API-Key mit entsprechenden Berechtigungen konfiguriert und die Erreichbarkeit des Plattformendpunkts über das Netzwerk sichergestellt sein. Weitere Informationen zur Installation und Verwendung der CaaS-Plattform finden Sie in der entsprechenden Dokumentation.
2. Installation des Moduls
Das Modul hat keine Abhängigkeiten auf andere Module und kann somit sehr einfach auf dem FirstSpirit-Server installiert werden. Da Projekte explizit als CaaS-Projekte ausgezeichnet werden müssen, erfolgt nach Installation des Moduls nicht automatisch direkt ein Abgleich des Datenbestandes. Damit das Modul erwartungsgemäß funktioniert, muss zwingend die Service-Komponente konfiguriert werden.
|
Nach Installation oder Aktualisierung des Moduls ist zwingend ein Neustart des FirstSpirit-Servers nötig. |
3. Komponenten
Im Folgenden werden alle Komponenten des Moduls und deren Adminstration beschrieben.
3.1. CaaS-Service
Die Service-Komponente CaaS Connect Service ist das Bindeglied zwischen den Projekten auf dem FirstSpirit-Server und der CaaS-Plattform. Damit Projektinhalte zur Plattform übertragen werden, muss der Service gestartet sein. Ist der Service gestoppt, findet kein Abgleich statt. Für den Betrieb des Services ist eine valide Konfiguration nötig. Der Konfigurationsdialog der Service-Komponente CaaS Connect Service zeigt an, welche Felder optional oder verpflichtend sind, oder wenn die Eingabe einen Fehler beinhaltet. Die Minimalkonfiguration umfasst eine erreichbare CaaS-Plattform und einen API-Key, der auf alle CaaS-Projekte lesenden und schreibenden Zugriff hat. Weitere Informationen zu API-Keys und Berechtigungen sind in der CaaS-Plattform-Dokumentation zu finden.
|
Die Tenant-ID darf aus maximal 63 Zeichen bestehen und Groß-/Kleinschreibung wird nicht beachtet. |
3.1.1. Medien-Deployment
Medienbinärdaten können entweder in der CaaS-Plattform oder in einem S3-kompatiblen Service abgelegt werden. Das Speichern der Binärdaten in der CaaS-Plattform ist die Standardkonfiguration. Sofern Binärdaten in einem S3-Service ausgeliefert werden sollen, muss die Konfiguration der Service-Komponente CaaS Connect Service entsprechend angepasst werden.
|
Wird das Medien-Deployment geändert, werden bisherige Binärdaten-URLs ungültig. Sobald ein Medium erneut geändert oder freigegeben wird, werden sowohl Binärdaten als auch URLs auf selbige aktualisiert. Gegebenenfalls ist ein direkter Vollabgleich gewünscht, sodass keine Änderung im Projekt stattfinden muss. Hierfür kann über die beiden automatisch erstellen Aufträge für jedes Projekt ein Vollabgleich ausgelöst werden. |
Konfiguration eines S3-Deployments: Es können sowohl Amazon S3, als auch S3-kompatible Services zur Auslieferung verwendet werden. Die Angabe eines S3-Endpunkts ist optional. Ist kein Endpunkt angegeben, wird davon ausgegangen, dass Amazon S3 angesteuert wird. In diesem Fall muss eine Client-Region angegeben werden, damit der Amazon-Endpunkt bestimmt werden kann. Er setzt sich so zusammen: s3.$clientRegion.amazonaws.com. Die Zugangsdaten für den S3-Service sind ebenfalls optional. Gibt es keine Angabe in der Konfiguration, werden Umgebungsvariablen und System Properties ausgewertet. Weitere Informationen zu einer solchen Konfiguration können der offiziellen Amazon S3-Dokumentation entnommen werden.
|
Sofern ein S3-kompatibler Service ohne eine CloudFront Domain benutzt wird, werden die Links der Binärdaten von Medien im Virtual Hosted-Style Format ausgegeben. Für genauere Informationen bezüglich des Formats und dessen Einschränkungen siehe Virtual hosting of buckets und Amazon S3 Path Deprecation Plan. |
3.2. ProjectApp
Erst das Hinzufügen der Projekt-Komponente CaaS Connect Projekt-App aktiviert das CaaS Connect-Modul für ein Projekt. Es sind keine projektspezifischen Konfigurationen möglich und somit nicht notwendig. Der Konfigurationsdialog der Projekt-Komponente kann jedoch geöffnet werden und zeigt die CaaS-Basis-URLs, die für das Projekt vorgesehen sind.
Das Hinzufügen der Projekt-Komponente erzeugt für das jeweilige Projekt zwei Aufträge CaaS Connect Release Generation und CaaS Connect Preview Generation. Diese führen für den Freigabe- oder Vorschaustand einen Vollabgleich für das Projekt durch.
|
Zum Abgleich des Datenbestands bereits vorhandener Projektinhalte können die beiden Aufträge genutzt werden, die nach dem Hinzufügen der Projekt-Komponente angelegt wurden. |
4. Automatisierte Konfiguration des Moduls
Neben der händischen Konfiguration über die FirstSpirit-Oberfläche, kann CaaS Connect auch über das Dateisystem konfiguriert werden. Hierfür muss lediglich eine JSON-Konfigurationsdatei angelegt werden. Der Service CaaS Connect Service lädt beim Start automatisch die Datei caasConnect.json, die im FirstSpirit-Server unter Pfad ./conf/modules/CaasConnect.CaasConnectService/caasConnect.json liegen muss. Die folgenden Beispiele zeigen die in der Konfigurationsdatei benötigte und unterstützte Struktur.
|
Die folgenden Beispielkonfigurationen dürfen nicht auf Test- oder Produktivsystemen eingesetzt werden und müssen durch kundenspezifische Werte ersetzt werden. |
caasConnect.json Datei
{
// Wo die CaaS Plattform erreichbar ist
"baseUrl":"http://localhost:8080",
// Der API-Key der für Datenübertragung zwischen Modul und Plattform verwendet wird
"apiKey": "ef27ef88-11c1-4ba0-946c-5c82d2880a18",
// Der Name oder Kürzel des Mandanten
"tenantId": "defaultTenant"
}caasConnect.json Datei
{
// Wo die CaaS Plattform erreichbar ist
"baseUrl":"http://localhost:8080",
// Der API-Key der für Datenübertragung zwischen Modul und Plattform verwendet wird
"apiKey": "ef27ef88-11c1-4ba0-946c-5c82d2880a18",
// Der Name oder Kürzel des Mandanten
"tenantId": "defaultTenant",
// Optional, zu verwenden wenn medien nach S3 deployt werden sollen anstatt in den CaaS
"mediaConnectorConfig" : {
"S3": {
// Wo der S3 Endpunkt erreichbar ist
"endpointUri": "http://localhost:9000",
// Optional, zu verwenden, wenn keine Umgebungsvariablen oder System Properties für S3 Credentials verwendet werden
"credentials": {
"accessKeyId": "mySecretS3KeyId",
"secretAccessKey": "mySecretS3AccessKey"
},
"bucketName": "examplebucketname",
"timeoutInSeconds": 10,
// Optional, zu verwenden wenn eine bestimmte Region für Amazon S3 verwendet werden soll
"clientRegion": "eu-central-1"
}
},
// Optional, wenn die CaaS Plattform oder andere Services (S3, CloudFront) über einen Proxy erreicht werden soll
"proxyAddress": "foo:123"
}|
Kommt es beim Lesen der Konfigurationsdatei durch den Service zu einem Fehler, wird eine entsprechende Fehlermeldung im FirstSpirit-Log ausgegeben. Da der Service ohne valide Konfigurationsdatei nicht starten kann, ist die Funktionalität des Moduls in diesem Fall stark eingeschränkt. |
|
Einige Eingaben unterliegen neben Optionalität noch weiteren Einschränkungen, beispielsweise kann ein Bucket-Name keine Großbuchstaben beinhalten. Ungültige Eingaben werden in der UI direkt angezeigt und können nicht gespeichert werden. Wird eine solche ungültige Konfiguration als Datei hinterlegt, kommt es zu oben genannter Fehlermeldung im FirstSpirit-Log und der Service startet nicht. |
|
Das Hinzufügen einer Projekt-Komponente zu einem Projekt ist über die FirstSpirit-API möglich. ModuleAdminAgent.installProjectApp("CaasConnect", caasConnectProjectAppName, project) |
5. Fehlerbehandlung
Durch ungültige Konfiguration oder Netzwerkprobleme kann es zu Fehlern auf Seiten des CaaS Connect-Moduls kommen. Alle Fehler werden im FirstSpirit-Log ausgegeben.
5.1. Netzwerkfehler oder Überlastung
Das Modul ist auf die einwandfreie Verfügbarkeit der CaaS-Plattform angewiesen. Ist die Plattform nicht erreichbar oder kann sie die eingehenden Anfragen nicht ausreichend schnell verarbeiten, versucht das Modul die Anfragen zu wiederholen. Führt auch dies nicht zum Erfolg, wird im FirstSpirit-Log ein Fehler ausgegeben und mögliche Änderungen am Datenbestand, die durch die durchgeführte Aktion ausgelöst wurden, werden nicht mit der CaaS-Plattform abgeglichen. Dem Redakteur wird der Fehler nicht mitgeteilt, daher ist das Überwachen des Serverlogs durch die Administration essentiell. Tritt ein Fehler auf, kann entweder durch Ausführen der Standard-Aufträge oder erneutes Durchführen der fehlgeschlagenen Aktion der Abgleich korrigiert werden.
5.2. Konfiguration des API-Keys
Der in der Service-Komponente konfigurierte API-Key wird verwendet, um alle Projekte auf dem Server mit der CaaS-Plattform abzugleichen. Der API-Key benötigt daher Schreib- und Leserechte für alle CaaS-Projekte, auf dem FirstSpirit-Server. Weitere Information zur Konfiguration von API-Keys finden Sie in der CaaS-Plattform-Dokumentation.
5.3. Push Benachrichtigungen (Change Streams)
Die Change Stream Definitionen sind in den Metadaten der Collections zu finden. Sie werden gleichzeitig mit der Collection angelegt. Sollten sie fehlen, können sie wiederhergestellt werden, indem ein neues Deployment in den CaaS per Auftrag angestoßen wird.
6. Rechtliche Hinweise
CaaS ist ein Produkt der e-Spirit AG, Dortmund, Germany.
Für die Verwendung des Produkts gilt gegenüber dem Anwender nur die mit der e-Spirit AG vereinbarte Lizenz.
Details zu möglicherweise fremden, nicht von der e-Spirit AG hergestellten, eingesetzten Software-Produkten, deren eigenen Lizenzen und gegebenenfalls Aktualisierungs-Informationen, finden Sie in der Datei META-INF/licenses.csv, die mit dem Modul ausgeliefert wird.
7. Hilfe
Der Technical Support der e-Spirit AG bietet qualifizierte technische Unterstützung zu allen Themen, die FirstSpirit™ als Produkt betreffen. Weitere Hilfe zu vielen relevanten Themen erhalten und finden Sie in auch in unserer Community.