Installationsanleitung

🛈 Hinweis
In den nachfolgenden Beispielen werden zur Veranschaulichung die Datenbank test und der Server https://www.myserver.com verwendet (z.B. im Pfad https://www.myserver.com/api/test). Diese Datenbank bzw. dieser Server ist in allen echten Aufrufen entsprechend zu ersetzen. Je nach Konfiguration muss die URL gegebenenfalls auch noch um den Context-Path erweitert werden (z.B. https://www.myserver.com/dataspot/api/test).

What's new?

Folgende Änderungen an der Konfiguration sind zu beachten:

Release	Beschreibung
2026.1	Der Server-Parameter `DATASPOT_VERSION_HISTORY_RETENTION` definiert die Behaltedauer von historischen Versionen.
2025.1	Zur Unterstützung beim Eingeben und Bearbeiten von Texten durch künstliche Intelligenz kann ein AI Provider konfiguriert werden.
2025.1	`JdbcMetadataConnector` wird durch `dataspot. Connector` ersetzt. `JdbcMetadataConnector` wird in Release 2025.1 ausgeliefert und unterstützt jedoch ab Release 2026.1 nicht mehr ausgeliefert. Bestehende Integrationen müssen auf `dataspot. Connector` umgestellt werden.
2025.1	Der Server-Parameter `DATASPOT_MAIL_OAUTH` aktiviert den Versand von E-Mails mit Microsoft Graph und einer Authentifizierung mit OAuth 2.0.
4.5	Für den Betrieb vor Ort (On-Premises) ist PostgreSQL 14 (ab 14.11) oder 15 erforderlich.
4.5	Für den Betrieb vor Ort (On-Premises) sowie zum Ausführen der Metadata Konnektoren ist Java 17 erforderlich.
4.5	Der Server-Parameter `DATASPOT_HTTP_SECURE_ONLY` aktiviert/deaktiviert zusätzlichen Schutz gegen XSS (Cross-Site-Scripting) und MITM-Angriffe (Man-in-the-Middle).
4.5	Der Server-Parameter `DATASPOT_POSTGRES_CONNECTION_PARAMS` definiert zusätzliche Optionen für die Datenbankverbindung und erlaubt z.B. die Verschlüsselung über SSL/TLS, falls der PostgreSQL-Server entsprechend konfiguriert ist.
4.4	Die Server-Parameter `DATASPOT_PROCESS_NOTIFICATIONS_CRON` und `DATASPOT_VALIDATE_ASSETS_CRON` haben neue Default-Werte.
4.3	Die Server-Parameter `DATASPOT_POSTGRES_READONLY_USER` und `DATASPOT_POSTGRES_READONLY_PASSWORD` definieren den Benutzer in PostgreSQL, mit dem kundenspezifische, ausschließlich lesende SQL-Abfragen abgesetzt werden können.
4.2	Der Server-Parameter `DATASPOT_REORG_DATABASES_CRON` definiert den Zeitpunkt für das regelmäßige Löschen von alten Jobs und alten Benachrichtigungen.
4.2	Der Server-Parameter `DATASPOT_VALIDATE_ASSETS_CRON` definiert den Zeitpunkt für die regelmäßige Prüfung von Regelverletzungen.
4.2	Der Server-Parameter `DATASPOT_JOB_RETENTION` definiert die Behaltedauer von Jobs sowie deren gegebenenfalls bereitgestellten Downloads.
4.2	Der Server-Parameter `DATASPOT_MANUAL_URL` definiert die URL zu einem kundenspezifischen Handbuch, das durch Klick auf das Symbol in der Menüleiste geöffnet wird.

Installation als Docker-Container

Die Server-Komponente wird mit den nötigen Docker-Konfigurationen (Dockerfile) geliefert, um ein Image bzw. einen Container zu erstellen, in dem alle notwendigen Software-Pakete und Umgebungsvariablen vorkonfiguriert sind.

Speicherbedarf:

ca. 2 GB für das Docker-Image
mindestens 10 GB zusätzlicher Plattenspeicher

Grundsätzlich kann dataspot jede beliebige PostgreSQL-Instanz (siehe PostgreSQL Konfiguration) verwenden. Das nachfolgende Beispiel zeigt, wie dataspot gemeinsam mit PostgreSQL in einer Docker-Installation konfiguriert werden kann.

Zum einfachen Erzeugen bzw. Starten des Containers kann docker-compose verwendet werden (siehe Server-Parameter).

Beispiel: `docker-compose.yml`

version: '3'

services:
  dataspot:
    container_name: dataspot
    depends_on:
      - postgres
    build:
      context: ./dataspot
      args:
        WARFILE: dataspot-v<release>.war
    volumes:
      - dataspot_db:/data/dataspot
      - /data/backup:/data/backup
    environment:
      - DATASPOT_ADMIN_PASSWORD=<admin_password>
      - DATASPOT_BACKUP_DATABASES_CRON=0 1 * * *
      - DATASPOT_APPROVE_TICKETS_CRON=0 22 * * 1-5
      - DATASPOT_POSTGRES_HOST=postgres
      - DATASPOT_POSTGRES_USER=postgres
      - DATASPOT_POSTGRES_PASSWORD=<postgres_password>
      - DATASPOT_POSTGRES_PATH=/usr/lib/postgresql/15/bin # PostgreSQL 15.x
      - CATALINA_OPTS="-XX:MaxRAMPercentage=75.0" # increase max heap space to 75% of the available RAM
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/status" ]
      interval: 30s
      retries: 3

  postgres:
    container_name: postgres
    image: postgres:15.15
    shm_size: 1g
    volumes:
      - postgres_db:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=<postgres_password>

volumes:
  postgres_db:
  dataspot_db:

⚠️ Achtung
Wenn ein Docker-Container über TCP/IP erreichbar sein soll, müssen in docker-compose.yml die entsprechenden Public Ports explizit nach außen freigeschaltet werden (siehe Docker Dokumentation).

🛈 Hinweis
Die Größe des Shared-Memory für den PostgreSQL-Container muss gegebenenfalls erhöht werden (z.B.: shm_size: 1g).

Vorausgesetzt die Dateien dataspot-v<release>.war und Dockerfile befinden sich im Verzeichnis ./dataspot und das Backup-Verzeichnis /data/backup existiert auf dem Host-System von Docker, können die Container dataspot und postgres wie folgt erzeugt und gestartet werden:

$ docker-compose build dataspot
$ docker-compose up -d dataspot

Installation als WAR-Datei

Alternativ kann die Server-Komponente als Java WAR-Datei (Web Application Archive) installiert werden. Das Deployment der WAR-Datei muss in einem bereits installierten Java-EE-konformen Servlet-Container (z.B. Tomcat) erfolgen.

Die Konfiguration erfolgt entweder über Umgebungsvariablen oder über ServletContext-Parameter (siehe Server-Parameter).

Speicherbedarf:

ca. 500 MB für die WAR-Datei
mindestens 10 GB zusätzlicher Plattenspeicher

Voraussetzungen JDK/Servlet-Container:

dataspot wird mit JDK 17 und Tomcat 9 getestet. Das Funktionieren davon abweichender Konfigurationen kann derzeit nicht garantiert werden.

Für die Erstellung der Diagramme muss am Server zusätzlich das folgende Open-Source-Paket installiert sein:

graphviz

Um die Backup/Restore Funktionalität von dataspot zu nutzen, ist die Installation des folgenden Pakets notwendig:

postgresql-client-14

Unter Linux können diese Pakete üblicherweise über die entsprechenden Paket-Manager der verwendeten Distribution installiert werden.

Tomcat-Konfiguration

Die ausgelieferte WAR-Datei (Web Application Archive) muss in das Deployment-Verzeichnis /webapps von Tomcat kopiert werden. Angenommen das Installationsverzeichnis von Tomcat ist $CATALINA_HOME, dann muss die WAR-Datei in das Verzeichnis $CATALINA_HOME/webapps kopiert werden.

Die WAR-Datei wird von Tomcat automatisch in ein Unterverzeichnis entpackt, welches den gleichen Namen wie die WAR-Datei hat. Zum Beispiel, die WAR-Datei dataspot.war wird automatisch in das Verzeichnis $CATALINA_HOME/webapps/dataspot entpackt.

Der Context-Path (d.h. der relative Pfad der Web-Applikation am Server) ergibt sich aus dem Namen der WAR-Datei (bzw. vom entpackten Verzeichnis). Zum Beispiel, angenommen die WAR-Datei lautet dataspot.war, dann ist die Applikation unter folgender URL erreichbar:

https://www.myserver.com/dataspot/

⚠️ Achtung
Die Konfigurationsdatei muss gleich benannt sein wie die dazugehörige WAR-Datei. Zum Beispiel, wenn die Konfigurationsdatei dataspot.xml lautet, dann muss die ausgelieferte WAR-Datei (typischerweise dataspot-v<release>.war) auf dataspot.war umbenannt werden. Die WAR-Datei sollte vor dem Kopieren in das Deployment-Verzeichnis von Tomcat umbenannt werden, um zu verhindern, dass beim automatischen Entpacken ein Verzeichnis mit dem falschen, alten Namen erstellt wird.

Um die Web-Applikation zu aktualisieren, z.B. durch eine neue Release, muss sowohl die WAR-Datei im Verzeichnis $CATALINA_HOME/webapps ersetzt werden als auch das von Tomcat entpackte Verzeichnis (mit der alten Version) gelöscht werden. Anschließend wird Tomcat neu gestartet.

💡 Tooltipp
Um die Web-Applikation ohne Context-Path zu deployen kann die WAR-Datei (vor dem Kopieren in das Deployment-Verzeichnis) auf ROOT.war umbenannt werden. Die Applikation ist dann (ohne Context-Path) unter der URL https://www.myserver.com/ erreichbar.

Dataspot verwendet komprimierte Dateien, um die Datenübertragung für manche Artefakte gering zu halten. Um dieses Feature zu nutzen, muss der Initialisierungs-Parameter (init-param) namens gzip im DefaultServlet gesetzt sein.

Beispiel: `/usr/local/tomcat/conf/web.xml`

<servlet>
  <servlet-name>default</servlet-name>
  <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
+  <init-param>
+    <param-name>gzip</param-name>
+    <param-value>true</param-value>
+  </init-param>
  [..]
</servlet>

🛈 Hinweis
Weitere Informationen zur Installation von Tomcat bzw. zum Deployment von Web-Applikationen finden sich in der Dokumentation von Tomcat.

Installation des Frontend

Das Frontend von dataspot ist Browser-basiert. Eine Installation von Software am Client ist daher nicht notwendig.

Unterstützte Browser:

Google Chrome
Apple Safari
Microsoft Edge
Mozilla Firefox

Server-Parameter

Die Konfiguration von dataspot erfolgt über Server-Parameter. Server-Parameter können entweder als Umgebungsvariablen (typischerweise für die Docker-Installation) oder als ServletContext-Parameter (Installation als WAR-Datei) definiert werden.

🛈 Hinweis
Wenn ein Server-Parameter als Umgebungsvariable angegeben wird, gilt die unten angeführte Schreibweise mit dem Präfix DATASPOT_, in Großbuchstaben und getrennt durch _ (z.B. DATASPOT_ADMIN_PASSWORD). Als ServletContext-Parameter muss der Präfix DATASPOT_ weggelassen und der Name in camelCase Schreibweise angegeben werden. Zum Beispiel wird aus der Umgebungsvariable DATASPOT_ADMIN_PASSWORD der Context-Parameter adminPassword.

Die nachfolgenden, allgemeinen Server-Parameter werden unterstützt. Weitere Server-Parameter sind in den jeweiligen Abschnitten (PostgreSQL, Benutzerkennung und Passwort, Single Sign-On, Same Sign-In, OpenID Connect, E-Mail Benachrichtigungen) beschrieben.

Parameter	Beschreibung
`DATASPOT_ADMIN_PASSWORD`	Passwort für den System-Administrator (Benutzername: `admin`), der Datenbanken und Benutzer verwalten kann
`DATASPOT_DATA_PATH`	Verzeichnispfad für Daten, die im File-System gespeichert werden - default: `/data/dataspot`
`DATASPOT_BACKUP_PATH`	Verzeichnispfad für Backups - default: `/data/backup`
`DATASPOT_BACKUP_ROTATION`	Anzahl der Backups, die für die jeweiligen Zeiteinheiten behalten werden sollen: Tag, Woche, Monat und Jahr (nicht mehr benötigte Backups werden nach dem automatischen Backup gelöscht) - default: `off` (Backups werden nicht automatisch gelöscht) - example: `15` (Backups der letzten 15 Tage, sowie jeweils eines für die letzten 15 Wochen, 15 Monate und 15 Jahre bleiben erhalten)
`DATASPOT_EXTERNAL_URL`	URL (ohne Context-Path), unter welcher dataspot von außen erreichbar ist - example: `https://www.myserver.com`
`DATASPOT_MANUAL_URL`	URL zu einem kundenspezifischen Handbuch, das durch Klick auf das Symbol in der Menüleiste geöffnet wird. Vor dem Öffnen wird der optionale Platzhalter `${LANGUAGE}` durch die aktuelle Sprache (`de`, `en`) ersetzt. - optional; default: Das mitgelieferte Handbuch von dataspot wird geöffnet - example: `https://www.myserver.com/manual/index.html` - example: `https://www.myserver.com/manual/${LANGUAGE}/index.html`
`DATASPOT_DEFAULT_DB`	Default-Datenbank, auf die automatisch umgeleitet werden soll, falls die URL zur Applikation keine Datenbank enthält - optional; example: `test` (die URL `https://www.myserver.com` wird automatisch auf `https://www.myserver.com/web/test` umgeleitet)
`DATASPOT_BACKUP_DATABASES_CRON` `DATASPOT_BACKUP_TIME`(deprecated)	Zeitpunkt (Crontab-Expression) für das regelmäßige Backup aller Datenbanken, oder `off` (deaktiviert) - optional; default: `off` (deaktiviert)
`DATASPOT_APPROVE_TICKETS_CRON`	Zeitpunkt (Crontab-Expression) für den regelmäßigen Freigabeprozess, oder `off` (deaktiviert) - optional; default: `0 22 * * 1-5` (Montag bis Freitag, um 22:00)
`DATASPOT_PROCESS_NOTIFICATIONS_CRON`	Zeitpunkt (Crontab-Expression) für den regelmäßigen Benachrichtigungsprozess, oder `off` (deaktiviert) - optional; default: `0 3 * * *` (Täglich, um 03:00)
`DATASPOT_VALIDATE_ASSETS_CRON`	Zeitpunkt (Crontab-Expression) für die regelmäßige Prüfung von Regelverletzungen, oder `off` (deaktiviert) - optional; default: `0 4 * * *` (Täglich, um 04:00)
`DATASPOT_REORG_DATABASES_CRON`	Zeitpunkt (Crontab-Expression) für das regelmäßige Löschen von - alten Jobs (siehe `DATASPOT_JOB_RETENTION`) - alten Benachrichtigungen (siehe `DATASPOT_NOTIFICATION_RETENTION`) - alten historischen Versionen (siehe `DATASPOT_VERSION_HISTORY_RETENTION`) oder `off` (deaktiviert) - optional; default: `0 22 * * 6` (Jeden Samstag, um 22:00)
`DATASPOT_JOB_RETENTION`	Behaltedauer (Format) von Jobs sowie deren gegebenenfalls bereitgestellten Downloads. Ältere Jobs und Downloads werden automatisch gelöscht (siehe `DATASPOT_REORG_DATABASES_CRON`). - optional; default: `10d` (10 Tage)
`DATASPOT_NOTIFICATION_RETENTION`	Behaltedauer (Format) von Benachrichtigungen. Ältere Benachrichtigungen werden automatisch gelöscht (siehe `DATASPOT_REORG_DATABASES_CRON`). - optional; default: `90d` (90 Tage)
`DATASPOT_VERSION_HISTORY_RETENTION`	Behaltedauer (Format) von historischen Versionen. Ältere historische Versionen werden automatisch gelöscht (siehe `DATASPOT_REORG_DATABASES_CRON`). - optional; default: `forever` (niemals löschen)
`DATASPOT_WEB_SOCKETS`	Aktiviert/Deaktiviert Benachrichtigungen über WebSockets [`true`,`false`] - default: `false`
`DATASPOT_LOGGING_LEVEL`	Logging Level [`DEBUG`,`INFO`,`WARN`,`ERROR`] - default: `ERROR`
`DATASPOT_DEFAULT_VALID_FROM_DATE`	Minimal-Timestamp - default: `1900-01-01T00:00:00.000`
`DATASPOT_DEFAULT_VALID_TO_DATE`	Maximal-Timestamp - default: `2999-12-31T23:59:59.999`
`DATASPOT_DBCP_VALIDATION_QUERY_TIMEOUT`	Der Timeout (in Sekunden) der verwendet wird, um eine Datenbank-Verbindung im Connection-Pool zu validieren - default: `2` (Sekunden)
`DATASPOT_HTTP_SECURE_ONLY`	Aktiviert/Deaktiviert zusätzlichen Schutz gegen XSS (Cross-Site-Scripting) und MITM-Angriffe (Man-in-the-Middle) [`true`,`false`]. Falls aktiviert, werden Cookies vor Zugriff durch clientseitige Skripts geschützt sowie ausschließlich über HTTPS übertragen. - optional; default: `true`

⚠️ Achtung
Der zusätzliche Schutz gegen XSS (Cross-Site-Scripting) und MITM-Angriffe (Man-in-the-Middle) (siehe DATASPOT_HTTP_SECURE_ONLY) lässt die Applikation nur mit HTTPS korrekt funktionieren. Um die Applikation direkt nach der Installation über HTTP testen zu können, z.B. noch bevor TLS-Terminierung über einen Proxy verfügbar ist, kann der zusätzliche Schutz gegen XSS und MITM-Angriffe temporär deaktiviert werden. Es wird jedoch ausdrücklich empfohlen, den Schutz wieder zu aktivieren, sobald der Betrieb mittels HTTPS möglich ist.

🛈 Hinweis
Die URL DATASPOT_EXTERNAL_URL wird in Benachrichtigungen (z.B. über E-Mails) und in erzeugten PDFs verwendet, um Metadatenobjekte in dataspot zu referenzieren. Dataspot sollte daher über diese URL von außen erreichbar sein.

💡 Tooltipp
Alle regelmäßigen Prozesse, die durch eine Crontab-Expression gesteuert werden (DATASPOT_BACKUP_DATABASES_CRON, DATASPOT_APPROVE_TICKETS_CRON, DATASPOT_PROCESS_NOTIFICATIONS_CRON), können durch die Angabe von off deaktiviert werden.

🛈 Hinweis
Falls DATASPOT_WEB_SOCKETS aktiviert ist, muss sichergestellt werden, dass die WebSocket-Verbindung nicht von einem vorhandenen Proxy-Server geschlossen wird. Gegebenenfalls muss der entsprechende Timeout am Proxy-Server konfiguriert werden.

🛈 Hinweis
Benachrichtigungen werden nicht in Echtzeit verschickt. Stattdessen werden zur angegebenen Zeit (DATASPOT_PROCESS_NOTIFICATIONS_CRON) alle ungelesenen Benachrichtigungen (seit dem letzten Durchlauf) per E-Mail an die entsprechenden Personen verschickt. Es werden nur Benachrichtigungen verschickt, bei denen in den Benutzereinstellungen Als E-Mail senden aktiviert ist.

⚠️ Achtung
Es wird nicht empfohlen, zwischen Applikationsserver und Datenbankserver eine Firewall (oder Load Balancer) zu betreiben, die bestehende, ungenutzte Verbindungen nach einem Timeout automatisch trennt. Sollte das trotzdem der Fall sein, dann kann mit dem Server-Parameter DATASPOT_DBCP_VALIDATION_QUERY_TIMEOUT eingestellt werden, wie lange dataspot auf eine (gegebenenfalls getrennte) Datenbank-Verbindung warten soll, bevor sie neu aufgebaut wird. Falls die Applikation über einen Proxy-Server oder Reverse-Proxy erreicht wird, dürfen die verwendeten HTTP-Methoden (GET, POST, PUT, PATCH, DELETE) nicht blockiert werden.

Für alle Attribute (mit Ausnahme des Passworts) gibt es vorkonfigurierte Default-Werte. Um zu verhindern, dass die konfigurierten Werte durch die Default-Werte wieder überschrieben werden, muss bei der Konfiguration des Context-Parameters das XML-Attribut override="false" hinzugefügt werden.

Beispiel: `/usr/local/tomcat/conf/Catalina/localhost/dataspot.xml`

<Context>
    <Parameter name="adminPassword" value="s3cr3t"/>
    <Parameter name="dataPath" value="/data/dataspot" override="false"/>
    <Parameter name="backupPath" value="/data/backup" override="false"/>
    <Parameter name="backupDatabasesCron" value="0 1 * * *" override="false"/>
    <Parameter name="approveTicketsCron" value="0 22 * * 1-5" override="false"/>
    <Parameter name="loggingLevel" value="ERROR" override="false"/>
    <Parameter name="defaultValidFromDate" value="1900-01-01T00:00:00.000" override="false"/>
    <Parameter name="defaultValidToDate" value="2999-12-31T23:59:59.999" override="false"/>
    <Parameter name="postgresUser" value="postgres" override="false"/>
    <Parameter name="postgresPassword" value="<postgres_password>" override="false"/>
</Context>

⚠️ Achtung
Die Datei dataspot.xml muss gleich benannt sein wie die dazugehörige WAR-Datei, d.h. die ausgelieferte WAR-Datei (typischerweise dataspot-v<release>.war) muss gegebenenfalls auf dataspot.war umbenannt werden.

Crontab-Expression

Mittels Crontab-Expression kann für bestimmte Server-Parameter ein wiederkehrender Zeitpunkt definiert werden. Der Zeitpunkt wird durch fünf Werte festgelegt:

*    *    *    *    *
|    |    |    |    |       
|    |    |    |    Wochentag (0 - 6, Sonntag = 0)
|    |    |    |
|    |    |    Monat (1 - 12)
|    |    |
|    |    Tag des Monats (1 - 31)
|    |
|    Stunde (0 - 23)
|
Minute (0 - 59)

Ein Stern * bedeutet, dass der jeweilige Eintrag nicht beschränkt ist und einen beliebigen Wert haben kann.
- Zum Beispiel: Stunde mit dem Wert * bedeutet jede Stunde; Tag des Monats mit dem Wert * bedeutet jeden Tag.
Ein Komma , definiert eine Liste von Werten.
- Zum Beispiel: Minute mit der Werteliste 0,15,30,45.
Ein Bindestrich - definiert einen Bereich von Werten.
- Zum Beispiel: 1-6 bedeutet die Werte von 1 bis 6 (gleichbedeutend mit 1,2,3,4,5,6).
Ein Schrägstrich / definiert eine Schrittweite, d.h. das Überspringen einer festgelegten Anzahl von Werten.
- Zum Beispiel: Minute mit dem Wert */15 bedeutet alle 15 Minuten (gleichbedeutend mit 0,15,30,45).

🛈 Hinweis
Bei mehrdeutigen Einträgen muss nur eines der Kriterien erfüllt sein. Zum Beispiel, wenn sowohl Tag des Monats als auch Wochentag beschränkt sind (d.h. nicht *) dann muss das aktuelle Datum nur eines dieser beiden Kriterien erfüllen.

Beispiel	Bedeutung
`* * * * *`	Jede Minute
`/10 * * *`	Alle 10 Minuten
`0 17 * * 0`	Jeden Sonntag, um 17:00
`0 1 * * 2-5`	Dienstag bis Freitag, um 01:00
`30 07,09,13,15 * * *`	Täglich, um 07:30, 09:30, 13:30, 15:30
`0 /4 * *`	Alle vier Stunden
`0 1 1,15 * *`	Am 1. und 15. des Monats, um 01:00
`0 22 1 * 0`	Jeden Sonntag oder am 1. des Monats, um 22:00

PostgreSQL

⚠️ Achtung
Die Installation von PostgreSQL ist für den Betrieb von dataspot notwendig.

Zum Betrieb von dataspot kann jede beliebige, bereits vorhandene PostgreSQL-Installation verwendet werden.

Speicherbedarf:

je nach Größe der Datenbank, Plattenspeicher (> 100 GB)

🛈 Hinweis
Dataspot wird mit PostgreSQL 14.x, 15.x, 16.x und 17.x getestet. Die Kompatibilität zu anderen Versionen von PostgreSQL muss bei Bedarf bei dataspot nachgefragt und evaluiert werden.

⚠️ Achtung
Die Metadaten-Abfrage und das Metadata Query-API führen kundenspezifische SQL-Anweisungen auf die Metadata SQL Views durch. Um zu verhindern, dass lang laufende SQL-Abfragen negative Auswirkungen auf die Leistung oder Verfügbarkeit der Datenbank oder Applikation haben, wird empfohlen, die Laufzeit von SQL-Anweisungen zu beschränken. Der Parameter statement_timeout in PostgreSQL gibt die maximale Laufzeit (in Millisekunden) an, nach deren Ablauf eine SQL-Anweisung automatisch abgebrochen wird.

Die Konfiguration erfolgt über folgende Server-Parameter:

Parameter	Beschreibung
`DATASPOT_POSTGRES_HOST`	PostgreSQL-Server Name - default: `localhost`
`DATASPOT_POSTGRES_PORT`	PostgreSQL-Server Port - default: `5432`
`DATASPOT_POSTGRES_USER`	Benutzer mit entsprechender Berechtigung (siehe unten)
`DATASPOT_POSTGRES_PASSWORD`	Passwort (siehe `DATASPOT_POSTGRES_USER`)
`DATASPOT_POSTGRES_READONLY_USER`	Benutzer, mit dem kundenspezifische, ausschließlich lesende SQL-Abfragen abgesetzt werden können
`DATASPOT_POSTGRES_READONLY_PASSWORD`	Passwort (siehe `DATASPOT_POSTGRES_READONLY_USER`)
`DATASPOT_POSTGRES_CONNECTION_PARAMS`	Zusätzliche Optionen für die Datenbankverbindung - optional - example: `ssl=true&sslmode=require` (die Datenbankverbindung wird über SSL/TLS verschlüsselt) - example: `ssl=true&sslmode=verify-ca` (die Datenbankverbindung wird über SSL/TLS verschlüsselt und das Serverzertifikat wird verifiziert)
`DATASPOT_POSTGRES_PATH`	Verzeichnis der PostgreSQL-Utilities (`pg_dump`, `pg_restore`, usw.) - default: `/usr/bin` ⚠️ Die Utilities müssen zur PostgreSQL-Version passen, die von der Applikation verwendet wird!
`DATASPOT_POSTGRES_DB`	Liste von PostgreSQL Datenbanken, die von dataspot verwendet werden können - optional (siehe PostgreSQL Konfiguration, Option 2)

⚠️ Achtung
Um die Datenbankverbindung über SSL/TLS zu verschlüsseln (siehe Server-Parameter DATASPOT_POSTGRES_CONNECTION_PARAMS), muss der PostgreSQL-Server entsprechend konfiguriert sein:

Das Serverzertifikat (z.B. server.crt) und der private Schlüssel (z.B. server.key) müssen vorhanden sein.

Die Verschlüsselung über SSL/TLS muss aktiviert sein (postgresql.conf).

Die Authentifizierungsregeln müssen gegebenenfalls angepasst werden (pg_hba.conf).

💡 Tooltipp
Um zu überprüfen, welche Datenbankverbindungen über SSL/TLS verschlüsselt sind, kann folgende SQL-Abfrage abgesetzt werden:

select pg_ssl.pid, pg_ssl.ssl, pg_ssl.version, pg_sa.backend_type,
       pg_sa.usename, pg_sa.client_addr
from pg_stat_ssl pg_ssl join pg_stat_activity pg_sa on pg_ssl.pid = pg_sa.pid;

🛈 Hinweis
Die Server-Parameter DATASPOT_POSTGRES_READONLY_USER und DATASPOT_POSTGRES_READONLY_PASSWORD definieren einen Benutzer in PostgreSQL, mit dem das Abfragen von Metadaten mit kundenspezifischen SQL-Anweisungen entweder mit der Metadaten-Abfrage in der Benutzeroberfläche oder mit dem Metadata Query-API möglich ist.

Beim Starten des Applikationsservers wird überprüft, ob der Benutzer bereits in der Datenbank existiert. Falls der Benutzer nicht existiert, wird der Benutzer (mit dem angegebenen Passwort) automatisch angelegt und bekommt ausschließlich lesende Berechtigungen für alle Metadata SQL Views. Alternativ dazu kann der Benutzer mitsamt den erforderlichen Berechtigungen von einem Datenbank-Administrator selbstständig angelegt werden.

Je nach Berechtigung des Benutzers DATASPOT_POSTGRES_USER gibt es für die Anbindung zwei Optionen.

Option 1: `CREATEDB` Berechtigung für die PostgreSQL-Instanz

In dieser Variante hat dataspot die Berechtigung, Datenbanken in der PostgreSQL-Instanz zu verwalten. Datenbanken können somit über die Admin-Konsole von dataspot angelegt, gelöscht, gesichert und wiederhergestellt werden.

Erzeugen eines PostgreSQL-Benutzers für dataspot

Der folgende Befehl erzeugt einen Benutzer namens dataspot, der CREATEDB Berechtigung hat:

$ createuser -h <host> -p <port> -U <superuser> -W <password> -d -P dataspot
  Enter password for new role: ***** 
  Enter it again: ******

🛈 Hinweis
Um diesem Benutzer superuser Berechtigung zu geben, kann optional die Option -s angegeben werden.

Option 2: `GRANT ALL` Berechtigung für das Schema `dataspot`

In dieser Variante hat dataspot nur Zugriff auf eine bestimmte Menge an vorkonfigurierten Datenbanken.

Erzeugen eines PostgreSQL-Benutzers für dataspot

Der folgende Befehl erzeugt einen Benutzer namens dataspot:

$ createuser -h <host> -p <port> -U <superuser> -W <password> -P dataspot
  Enter password for new role: ***** 
  Enter it again: ******

Dieser Benutzer hat keine Berechtigungen, um Datenbanken anzulegen.

⚠️ Achtung
In dieser Variante kann der Benutzer für das Abfragen von Metadaten mit kundenspezifischen SQL-Anweisungen (siehe Server-Parameter DATASPOT_POSTGRES_READONLY_USER und DATASPOT_POSTGRES_READONLY_PASSWORD) nicht automatisch angelegt werden. Der Benutzer muss von einem Datenbank-Administrator angelegt werden. Die erforderlichen Berechtigungen für das Schema dataspot sowie für alle Metadata SQL Views sind:

grant usage on schema dataspot to <user>
grant select on table dataspot.<view> to <user>

Erzeugen einer Datenbank zur Verwendung durch dataspot

Eine Datenbank kann von einem Datenbank-Administrator nach folgendem Muster angelegt werden:

$ createdb --h <host> -p <port> -U <superuser> db_001
$ psql -h <host> -p <port> -U <superuser> -W <password> -d db_001 -c "create schema dataspot;grant all on schema dataspot to dataspot;"

Damit eine Datenbank von dataspot verwendet werden kann, müssen ein logischer und ein physischer Name (getrennt durch einen Doppelpunkt) in der Server-Konfiguration angegeben werden:

Der logische Name der Datenbank wird von dataspot verwendet, um die Datenbank anzulegen und ist somit auch der für den dataspot Benutzer bzw. Administrator sichtbare Name der Datenbank.
Der physische Name ist der Datenbank-Name, unter dem der Datenbank-Administrator die Datenbank mit dem - wie oben beschrieben - vorkonfigurierten Schema dataspot angelegt hat.

Beispiel

Im folgenden Beispiel sind zwei Datenbanken zur Verwendung durch dataspot konfiguriert. In dataspot sind die Datenbanken als dxmeta und playground sichtbar. Auf dem Datenbank-Server sind diese Datenbanken als db_001 bzw. db_002 angelegt worden.

Die entsprechende Umgebungsvariable ist:

DATASPOT_POSTGRES_DB=dxmeta:db_001;playground:db_002

Der entsprechende ServletContext-Parameter ist:

<Context>
    <Parameter name="postgresDb" value="dxmeta:db_001;playground:db_002"/>
</Context>

In der Admin-Konsole von dataspot können jetzt nur diese konfigurierten Datenbanken verwaltet (d.h. von dataspot genutzt) werden. Beim Anlegen der Datenbank in der Admin-Konsole von dataspot werden die entsprechenden SQL-Objekte im Schema dataspot erzeugt.

Beim Löschen einer Datenbank in der Admin-Konsole von dataspot wird nicht die eigentliche Datenbank gelöscht, sondern das Schema dataspot wird wieder auf den Ausgangszustand zurückgesetzt.

Backup und Restore können für die konfigurierten Datenbanken über die Admin-Konsole durchgeführt werden. Alternativ bzw. zusätzlich können Backup und Restore auch außerhalb von dataspot erfolgen.

Max. Connections

Dataspot verwendet einen Connection-Pool für den Zugriff auf die PostgreSQL-Datenbanken. Standardmäßig lässt PostgreSQL maximal 100 Connections auf den Datenbank-Server zu. Je nach Anzahl der Datenbanken muss daher die maximale Anzahl der Datenbank-Connections eventuell erhöht werden.

🛈 Hinweis
Die maximale Anzahl der benötigten Datenbank-Connections kann berechnet werden als:
max_connections = (Anzahl Datenbanken + 1) * 8

Zum Beispiel, bei der Installation als Docker-Container kann das wie folgt konfiguriert werden:

postgres:
  [..]
  command: postgres -c 'max_connections=160'

Authentifizierung

Der Applikationsserver verbindet sich zur Datenbank mit Benutzername und einem verschlüsselten Passwort (scram-sha-256 oder md5), welches mit dem verschlüsselten Passwort am Datenbankserver verglichen wird.

Hinweis

Seit PostgreSQL 14.x werden Passwörter am Datenbankserver standardmäßig mit scram-sha-256 verschlüsselt gespeichert (postgresql.conf).

Um den Übergang von md5 auf scram-sha-256 zu erleichtern, wird die Authentifizierungsmethode scram-sha-256 automatisch ausgewählt, falls md5 als Authentifizierungsmethode angegeben ist (pg_hba.conf), das Passwort auf dem Datenbankserver jedoch mit scram-sha-256 verschlüsselt gespeichert ist.

Gegebenenfalls ist es notwendig, folgende Einstellung in der Konfiguration (pg_hba.conf) zu ändern:

host all all 127.0.0.1/32 scram-sha-256

Artificial Intelligence (AI)

Zur Unterstützung beim Eingeben und Bearbeiten von Texten durch künstliche Intelligenz (Artificial Intelligence, AI) kann ein AI Provider (z.B. Azure OpenAI Service) konfiguriert werden.

Die Konfiguration erfolgt über folgende Server-Parameter:

Parameter	Beschreibung
`DATASPOT_AI`	Aktiviert/Deaktiviert die Unterstützung durch AI [`true`,`false`] - default: `false`
`DATASPOT_AI_ENDPOINT`	Der Service-Endpunkt des AI Providers
`DATASPOT_AI_DEPLOYMENT_NAME`	Der Name der kundenspezifischen Modellbereitstellung (der Name der Bereitstellung wird im Portal des AI Providers frei gewählt und anschließend bei allen API Aufrufen verwendet)
`DATASPOT_AI_API_KEY`	Der geheime API Key, um sich zu authentifizieren (der API Key wird im Portal des AI Providers angelegt) - optional
`DATASPOT_AI_OAUTH`	Aktiviert/Deaktiviert die Authentifizierung mit OAuth 2.0 [`true`,`false`] - default: `false`
`DATASPOT_AI_OAUTH_TENANT_ID`	OAuth 2.0 Tenant-ID
`DATASPOT_AI_OAUTH_CLIENT_ID`	OAuth 2.0 Client-ID
`DATASPOT_AI_OAUTH_CLIENT_SECRET`	OAuth 2.0 Client Secret; Authentifizierung mit einem Client Secret - optional
`DATASPOT_AI_OAUTH_CERTIFICATE_FILE`	OAuth 2.0 Client Certificate; Authentifizierung mit einem Client Certificate (vollständiger Pfad) - optional; default: `/data/dataspot/certs/ai_oauth.pfx`
`DATASPOT_AI_OAUTH_CERTIFICATE_PASSWORD`	OAuth 2.0 Client Certificate Password; Falls das Client Certificate mit einem Passwort geschützt ist (siehe `DATASPOT_AI_OAUTH_CERTIFICATE_FILE`) - optional

E-Mail Benachrichtigungen

In dataspot gibt es die Möglichkeit, in bestimmten Phasen der Verarbeitung (z.B. bei Statusübergängen im Workflow-Prozess) automatische Benachrichtigungen (Notifications) als E-Mails zu versenden.

E-Mails können mit Microsoft Graph und einer Authentifizierung mit OAuth 2.0 (Client Secret oder Client Certificate) verschickt werden (siehe DATASPOT_MAIL_OAUTH). Alternativ kann ein SMTP-Server verwendet werden, um E-Mails zu verschicken (siehe DATASPOT_MAIL_SMTP).

Hinweis

Die Authentifizierung mit Benutzername und Passwort (Basic Auth) für SMTP wird von Microsoft Exchange Online (Microsoft 365) nicht mehr unterstützt.

Die Konfiguration erfolgt über folgende Server-Parameter:

Parameter	Beschreibung
`DATASPOT_MAIL_OAUTH`	Aktiviert/Deaktiviert E-Mail-Benachrichtigungen mit OAuth 2.0 [`true`,`false`] - default: `false`
`DATASPOT_MAIL_OAUTH_PROVIDER_URL`	OAuth 2.0 Provider URL
`DATASPOT_MAIL_OAUTH_CLIENT_ID`	OAuth 2.0 Client-ID
`DATASPOT_MAIL_OAUTH_CLIENT_SECRET`	OAuth 2.0 Client Secret; Authentifizierung mit einem Client Secret - optional
`DATASPOT_MAIL_OAUTH_CERTIFICATE_FILE`	OAuth 2.0 Client Certificate; Authentifizierung mit einem Client Certificate (vollständiger Pfad) - optional; default: `/data/dataspot/certs/mail_oauth.pfx`
`DATASPOT_MAIL_OAUTH_CERTIFICATE_PASSWORD`	OAuth 2.0 Client Certificate Password; Falls das Client Certificate mit einem Passwort geschützt ist (siehe `DATASPOT_MAIL_OAUTH_CERTIFICATE_FILE`) - optional
`DATASPOT_MAIL_SMTP`	Aktiviert/Deaktiviert E-Mail-Benachrichtigungen mit SMTP [`true`,`false`] - default: `false`
`DATASPOT_MAIL_SMTP_HOST`	SMTP-Server Name
`DATASPOT_MAIL_SMTP_PORT`	SMTP-Server Port - default: `587`
`DATASPOT_MAIL_SMTP_USER`	Benutzer, der die Berechtigung hat, am SMTP-Server E-Mails zu versenden
`DATASPOT_MAIL_SMTP_PASSWORD`	Passwort (siehe `DATASPOT_MAIL_SMTP_USER`)
`DATASPOT_MAIL_SMTP_AUTH`	Aktiviert/Deaktiviert Authentifizierung mittels `AUTH` Befehl [`true`,`false`] - optional; default: `true`
`DATASPOT_MAIL_SMTP_STARTTLS_ENABLE`	Aktiviert/Deaktiviert Verschlüsselung über TLS mittels `STARTTLS` Befehl [`true`,`false`] - optional; default: `true`
`DATASPOT_MAIL_FROM`	E-Mail-Header: Feld `From` (Absender)
`DATASPOT_MAIL_REPLY_TO`	E-Mail-Header: Feld `Reply-To` (Antwortadresse) - optional

Erste Schritte

Gratulation, die Installation von dataspot wurde erfolgreich abgeschlossen!

Admin-Konsole

Nach der Installation ist die Admin-Konsole von dataspot unter folgender URL erreichbar:

https://www.myserver.com/dataspot/web/admin

Der Login erfolgt mit dem System-Administrator admin und dem konfigurierten Passwort (siehe Server-Parameter DATASPOT_ADMIN_PASSWORD).

In der Admin-Konsole können Datenbanken angelegt und gelöscht bzw. aus einem Backup wiederhergestellt werden. Eine neu angelegte Datenbank namens <database> ist unter folgender URL erreichbar:

https://www.myserver.com/dataspot/web/<database>

Vordefinierte Datenbanken

Die vordefinierte Datenbank meta beschreibt das Metamodell von dataspot und dokumentiert alle Eigenschaften und Beziehungen der Metadatenobjekte. Das Metamodell bildet die Grundlage für alle Schnittstellen (Metadata REST/API, Metadata SQL Views, Metadata Upload/Download). Das Metamodell meta ist unter folgender URL erreichbar:

https://www.myserver.com/dataspot/web/meta

💡 Tooltipp
Die Datenbank meta kann in der Admin-Konsole angelegt und gelöscht bzw. auf den Werkszustand zurückgesetzt werden.

Benutzer anlegen

Der System-Administrator admin hat Zugriff auf jede Datenbank. Allerdings dürfen aus Governance-Gründen nur die Organisation bearbeitet sowie Benutzer angelegt, geändert und gelöscht werden. Um neue Modelle anzulegen, ist es daher notwendig, dass der System-Administrator als ersten Schritt einen Administrator (Metadatenmanager) für die Datenbank anlegt.

🛈 Hinweis
Gegebenenfalls kann der aktuelle Mandant im persönlichen Benutzer-Menü des System-Administrators, durch Klick in die Menüleiste auf das Symbol , gewählt werden.

Öffnen der Organisation in der Seitenleiste
Klick auf den Reiter "Personen" und auf das Symbol "+"
Anlegen der Person, die Administrator für die Datenbank sein soll
Öffnen des Mandanten in der Seitenleiste
Klick auf den Reiter "Benutzer" und auf das Symbol "+"
Anlegen eines Benutzers für den Administrator
- Login-ID und Passwort eingeben
- Die Zugriffsstufe auf Administrator setzen
- Die zuvor angelegte Person unter Ist Person auswählen
- Schaltfläche Anlegen klicken

Der angelegte Metadatenmanager kann sich jetzt für die angelegte Datenbank anmelden und hat für diese Datenbank alle Rechte (inklusive Benutzer anlegen, ändern und löschen).

🛈 Hinweis
Das dataspot Handbuch ist über das Symbol in der Menüleiste erreichbar.

What's new?​

Installation als Docker-Container​

Beispiel: docker-compose.yml​

Installation als WAR-Datei​

Tomcat-Konfiguration​

Beispiel: /usr/local/tomcat/conf/web.xml​

Installation des Frontend​

Server-Parameter​

Beispiel: /usr/local/tomcat/conf/Catalina/localhost/dataspot.xml​

Crontab-Expression​

PostgreSQL​

Option 1: CREATEDB Berechtigung für die PostgreSQL-Instanz​

Erzeugen eines PostgreSQL-Benutzers für dataspot​

Option 2: GRANT ALL Berechtigung für das Schema dataspot​

Erzeugen eines PostgreSQL-Benutzers für dataspot​

Erzeugen einer Datenbank zur Verwendung durch dataspot​

Beispiel​

Max. Connections​

Authentifizierung​

Artificial Intelligence (AI)​

E-Mail Benachrichtigungen​

Erste Schritte​

Admin-Konsole​

Vordefinierte Datenbanken​

Benutzer anlegen​

What's new?

Installation als Docker-Container

Beispiel: `docker-compose.yml`

Installation als WAR-Datei

Tomcat-Konfiguration

Beispiel: `/usr/local/tomcat/conf/web.xml`

Installation des Frontend

Server-Parameter

Beispiel: `/usr/local/tomcat/conf/Catalina/localhost/dataspot.xml`

Crontab-Expression

PostgreSQL

Option 1: `CREATEDB` Berechtigung für die PostgreSQL-Instanz

Erzeugen eines PostgreSQL-Benutzers für dataspot

Option 2: `GRANT ALL` Berechtigung für das Schema `dataspot`

Erzeugen eines PostgreSQL-Benutzers für dataspot

Erzeugen einer Datenbank zur Verwendung durch dataspot

Beispiel

Max. Connections

Authentifizierung

Artificial Intelligence (AI)

E-Mail Benachrichtigungen

Erste Schritte

Admin-Konsole

Vordefinierte Datenbanken

Benutzer anlegen