Relution Signet Customer Hub

Update

Die folgenden Schritte dienen zur Aktualisierung der Relution Installation.

Beim ersten Start nach dem Update aktualisiert Relution die Datenbank automatisch. Das kann einige Zeit dauern und darf nicht abgebrochen werden. Wird der Vorgang unterbrochen, kann eine Sperre in der Datenbank zurückbleiben, die den nächsten Start verhindert (siehe DatabaseChangeLogLock gesperrt →).

In einem Cluster werden beim Update über Relution 26.5.5 hinweg alle Knoten gemeinsam aktualisiert: Alle Knoten werden gestoppt, aktualisiert und erst danach wieder gestartet. Knoten mit einer Version vor 26.5.5 können nicht mit Knoten ab 26.5.5 kommunizieren, ein knotenweises Update im laufenden Betrieb ist über diese Versionsgrenze hinweg deshalb nicht möglich. Eine zusätzliche Konfiguration ist nicht erforderlich (siehe HA Cluster (Advanced) →).

Docker Installation

Die Datei compose.yaml (bei älteren Installationen docker-compose.yml) bearbeiten und
image: relution/relution:xxx mit image: relution/relution:latest ersetzen

Relution zu aktualisieren ist dann sehr einfach:

cd /opt/relution/
docker compose pull
docker compose up --detach

Bei neueren Docker Versionen hat sich die Schreibweise auf docker compose ohne Bindestrich geändert.

Dieser Befehl wird die neuste Version des Docker Images herunterladen und installieren. Der Relution Dienst wird für einige Minuten nicht erreichbar sein, solange der Container neu startet.

Mit dem folgenden Kommando können alte Container und Caches gelöscht werden, wodurch teilweise sehr viel Speicherplatz frei wird.

docker system prune -a

WARNING! This will remove:
  - all stopped containers
  - all networks not used by at least one container
  - all images without at least one container associated to them
  - all build cache

Are you sure you want to continue? [y/N]

Bekannte Fehlermeldungen

Update hängt bei GeneratedSelfSignedSignerKeyStore

Problem: Das Update bleibt beim Schritt GeneratedSelfSignedSignerKeyStore hängen.

Ursache: Ab Relution 26.3 wird aus Compliance-Gründen ein anderer kryptografischer Zufallszahlengenerator verwendet (ein DRBG nach NIST SP 800-90A). Ist kein eigenes iOS-Signaturzertifikat konfiguriert (siehe iOS-Signierungszertifikat →), erzeugt Relution beim Start damit ein selbstsigniertes Signaturzertifikat (GeneratedSelfSignedSignerKeyStore) mit einem 4096-Bit-RSA-Schlüssel.

Lösung: Update auf einen aktuellen Kernel bzw. ein aktuelles Rocky- oder Alma-Linux, wie in der Installationsanleitung Docker (empfohlen) → vorausgesetzt.

Datenbank-Update bricht wegen ungültiger UUIDs im Compliance-Verlauf ab

Problem: Beim ersten Start einer Version ab Relution 26.5.0 bricht das Datenbank-Update ab, und Relution startet nicht. Mit MariaDB enthält das Log die folgende Meldung (bzw. dieselbe Meldung für die Tabelle mdm_cmplnc_hstry_rsn):

There is UUIDs in the mdm_cmplnc_hstry table that are not a valid UUIDs.

Mit PostgreSQL schlägt der Changeset 20260810-001-postgres-pre-check-mdm_cmplnc_hstry (bzw. …-mdm_cmplnc_hstry_rsn) mit invalid input syntax for type uuid fehl.

Ursache: Ab Relution 26.5.0 werden die UUID-Spalten des Compliance-Verlaufs vom Text- auf den UUID-Datentyp der Datenbank umgestellt. Vorab prüft das Datenbank-Update, ob alle Einträge in mdm_cmplnc_hstry und mdm_cmplnc_hstry_rsn gültige UUIDs enthalten. Enthält ein Eintrag einen Wert, der keine gültige UUID ist, wird das Update angehalten.

Lösung: Die betroffenen Einträge müssen vor dem nächsten Start bereinigt werden. Das Vorgehen wird mit dem Relution-Support abgestimmt: Support-Ticket →

Relution startet nicht mit dem Speichertyp AzureStorage oder GridFS

Problem: Relution beendet sich beim Start mit folgender Meldung:

Relution cannot start because AzureStorage is no longer supported as a resource storage type. Please use a supported storage type: SQL, S3

Statt AzureStorage kann dort auch GridFS stehen.

Ursache: In der Konfiguration ist unter relution.storage.resourceStorageType (Umgebungsvariable RELUTION_STORAGE_RESOURCESTORAGETYPE) noch ein Speichertyp eingetragen, der nicht mehr unterstützt wird. GridFS wird seit Relution 5.24, Azure Storage seit Relution 5.27 nicht mehr unterstützt. Unterstützt sind nur noch SQL (Speicherung in der Datenbank) und S3 (Objektspeicher).

Lösung: In der Konfiguration einen unterstützten Speichertyp eintragen, für einen Objektspeicher S3, siehe Objektspeicher verbinden →. Der Umzug der Daten in ein anderes Speicher-Backend ist unter Migration MinIO zu SeaweedFS → beschrieben.

Native Installation Linux

  1. Das neuste Relution Paket herunterladen (Latest Relution Package →), z. B. direkt auf dem Server:

    wget https://repo.relution.io/package/latest/relution-package.zip

  2. Den Relution Dienst stoppen. Bei einer Installation nach der Anleitung Veraltet: Linux (Alma) → heißt der systemd-Dienst relution:

    sudo systemctl stop relution

    Meldet der Befehl Unit relution.service not loaded, wurde der Dienst unter einem anderen Namen angelegt. Der Name lässt sich über den laufenden Relution-Prozess ermitteln: Der erste Befehl zeigt die Prozess-ID (zweite Spalte), der zweite in der ersten Zeile den zugehörigen Dienst (z. B. ● relution.service):

    ps -ef | grep -i "[r]elution"
systemctl status <PID>

    In diesem und den folgenden Befehlen wird relution dann durch den ermittelten Dienstnamen ersetzt. Erscheint statt eines Dienstes eine Sitzung (session-….scope), läuft Relution nicht als Dienst, sondern wurde von Hand gestartet, z. B. über bin/relution-foreground.sh. In diesem Fall wird der Prozess beendet (Strg+C im zugehörigen Terminal oder sudo kill <PID>) und Relution nach dem Update auf dieselbe Weise wieder gestartet.

  3. Die Relution Datenbank sichern. Ältere Installationen verwenden MariaDB, neuere PostgreSQL. Welche Datenbank im Einsatz ist, zeigt der Eintrag type im Abschnitt relution.database der application.yml (mariadb oder postgresql). Dort stehen auch Host, Benutzer und am Ende der url der Datenbankname:

    sudo grep -A4 "database:" /opt/relution/application.yml

    Die folgenden Einzeiler gehen von einem Datenbankserver auf demselben Rechner sowie von Datenbank und Benutzer relution aus. Abweichende Werte werden entsprechend ersetzt. Das Passwort (password in der application.yml) wird beim Ausführen abgefragt. Die Sicherung wird mit dem aktuellen Datum im Dateinamen im aktuellen Verzeichnis abgelegt.

    Für MariaDB:

    mariadb-dump -h localhost -u relution -p --single-transaction --routines --triggers relution > relution_$(date +%F).sql

    Bei MariaDB-Versionen vor 10.5 heißt das Programm mysqldump, die Parameter bleiben gleich.

    Für PostgreSQL:

    pg_dump -h localhost -U relution -F c -f relution_$(date +%F).dump relution

    Die Sicherung im Custom-Format (-F c) wird bei Bedarf mit pg_restore wieder eingespielt.

  4. Das Installationsverzeichnis sichern

    sudo mv <INSTALL_DIR> <INSTALL_DIR>.bak

  5. Das Zip-Paket in das übergeordnete Verzeichnis von <INSTALL_DIR> extrahieren. Das Paket enthält den Ordner relution, der dabei als <INSTALL_DIR> neu entsteht, z. B.:

    unzip relution-package.zip -d /opt

  6. <INSTALL_DIR>.bak/application.yml nach <INSTALL_DIR>/application.yml kopieren, z. B.:

    sudo cp -p /opt/relution.bak/application.yml /opt/relution/application.yml

  7. Eigentümer und Rechte im <INSTALL_DIR>-Verzeichnis setzen. Das Installationsverzeichnis gehört root. Der Dienstbenutzer relution erhält nur in den Verzeichnissen log und branding Schreibrechte sowie Leserechte auf die application.yml, z. B.:

    sudo chown -R root:root /opt/relution
sudo mkdir -p /opt/relution/log /opt/relution/branding
sudo chown -R relution:relution /opt/relution/log /opt/relution/branding
sudo chown root:relution /opt/relution/application.yml && sudo chmod 640 /opt/relution/application.yml

    Kann der Dienstbenutzer relution die application.yml nicht lesen, startet Relution nicht. Wurde das Log-Verzeichnis über die Umgebungsvariable RELUTION_LOGS an einen anderen Ort gelegt, benötigt relution dort Schreibrechte. Das Verzeichnis branding verwaltet Relution selbst: Ist ein Branding aktiv, wird es bei jedem Start geleert und neu befüllt, eigene Dateien darin bleiben nicht erhalten.

    Ab Relution 26.5.8 meldet Relution beim Start im Log einen Fehler je Verzeichnis (portal, teacher, bin, lib), in dem der Dienstbenutzer schreiben kann (Installation path … is writable for the user running Relution). Das betrifft Installationen, deren Verzeichnis bisher vollständig relution gehörte (chown -R relution:relution). Der Start wird dadurch nicht verhindert. Nach dem Setzen der Rechte wie oben erscheint die Meldung beim nächsten Start nicht mehr.

  8. Den Relution Dienst starten:

    sudo systemctl start relution

  9. Warten, bis der Relution Dienst gestartet ist. Den Zustand des Dienstes zeigt systemctl status relution. Den Fortschritt des Starts zeigt die Logdatei relution.log, der Speicherort ist unter Relution Logs → beschrieben.

    Die Datenbank wird auf den neusten Stand geupdatet. Das Update der Datenbank kann etwas Zeit in Anspruch nehmen.

Native Installation Windows

  1. Das neuste Relution Paket herunterladen: Latest Relution Package →

  2. Den Relution-Dienst über die Diensteverwaltung (services.msc) stoppen

  3. Das bestehende Installationsverzeichnis nach relution_bak_ sichern

  4. Das Zip-Paket extrahieren und den darin enthaltenen Ordner relution als neues Installationsverzeichnis <INSTALL_DIR> ablegen (an derselben Stelle wie das bisherige Installationsverzeichnis)

  5. Die Konfigurationsdatei aus der Sicherung relution_bak_/application.yml nach <INSTALL_DIR>/application.yml kopieren

  6. Den Relution Dienst starten

  7. Warten, bis der Relution Dienst gestartet ist. Das Log wird in die Datei relution.log geschrieben, der Speicherort ist unter Relution Logs → beschrieben.

    Die Datenbank wird auf den neusten Stand geupdatet. Das Update der Datenbank kann etwas Zeit in Anspruch nehmen.

Bekannte Fehlermeldungen

Erscheint beim Starten des Relution-Dienstes die folgende Meldung, kann dies auf eine zu niedrige Java-Version hinweisen:

Der Dienst "Relution" auf "Lokalem Computer" konnte nicht gestartet werden
Der Dienst hat keinen Fehler zurückgegeben
Es kann sich um einen internen Windows-Fehler oder einen internen Dienstfehler handeln
Falls das Problem weiterhin besteht, den Systemadministrator kontaktieren

Zur Behebung die aktuelle Java 21 LTS von folgendem Link herunterladen und installieren: Adoptium Java →
Während der Installation die Option zum Setzen der Variable JAVA_HOME aktivieren (im Adoptium-Installer z. B. Set JAVA_HOME variable). Andernfalls muss die Systemvariable JAVA_HOME nachträglich manuell auf das Verzeichnis der neuen Java-Installation gesetzt werden (siehe Abschnitt „Prüfen ob JAVA_HOME gesetzt ist“ unter Veraltet: Windows Server 2019 →). Zeigt JAVA_HOME noch auf die alte Java-Version, startet der Dienst weiterhin nicht.
Nach der Installation den Relution-Dienst erneut starten.

Checkliste nach dem Update

  • Benötigen Relution Apps auf den mobilen Geräten ebenfalls ein Update?
  • Benötigen angepasste CSS Dateien ein Update?
  • Sind eingeschriebene Geräte noch erreichbar?
    • Eine Geräteinformationen aktualisieren-Aktion an ein Gerät senden
  • Funktioniert die Einschreibung für die verschiedenen Plattformen noch?

Update von 26.0.x auf 26.1 oder neuer schlägt fehl (MariaDB)

Problem: Beim Update von Relution 26.0.x auf Relution 26.1 oder neuer schlägt das automatische Datenbank-Update mit MariaDB mit der Fehlermeldung Cannot change column 'action_uuid' fehl. In den Server-Logs erscheint folgender Fehler:

java.sql.SQLException: (conn=1539) Cannot change column 'action_uuid': used in a foreign key constraint 'fk_mdm_sb_actn_action_uuid'

Ursache: Beim Relution-Update versucht Liquibase, einer Tabellenspalte einen NOT NULL-Constraint hinzuzufügen, die als Fremdschlüssel definiert ist. Bei den MariaDB-Versionen 10.11.5–10.11.7 schlägt das mit MariaDB-Fehler 1832 fehl — ein bekanntes MariaDB-Problem (MDEV-34392 →).

Lösung: Vor dem Relution-Update muss MariaDB aktualisiert werden. Empfohlen wird eine aktuelle LTS-Version (10.11.18, 11.4.12, 11.8.8 oder 12.3.2). Vor dem MariaDB-Update ist unbedingt ein vollständiges Backup der Datenbank anzulegen.

Hinweis: Update von Relution 5.x auf 26.1 oder neuer

Bei einem Update von Relution 5.3x.x auf Relution 26.1 oder neuer muss zwingend zuerst auf Relution 5.35.4 und anschließend auf die Zwischenversion Relution 26.0.3 aktualisiert werden. Relution 26.0.3 muss dabei mindestens einmal gestartet werden, damit beim Start die Datenbankmigration (u. a. der Gerätegruppen) abgeschlossen wird. Fehlt dieser Zwischenschritt oder ist die Migration nicht abgeschlossen, bricht das Datenbank-Update der neueren Version mit folgender Meldung ab:

An update from version 5 to 26.1+ detected. To proceed, it's necessary to install and start Relution version 26.0.0 at least once.

Relution 26 setzt MariaDB ab Version 10.11 oder PostgreSQL ab Version 14 voraus. Mit einer älteren Datenbankversion oder mit Microsoft SQL Server bzw. MySQL beendet sich der Server beim Start (siehe Migration MSSQL zu MariaDB →).

Docker

Bei Docker-Installationen kann die Version direkt in der compose.yaml festgelegt werden. Jeder Schritt wird wie oben mit docker compose pull und docker compose up --detach ausgeführt.

  1. Zuerst auf die letzte veröffentlichte 5.x-Version aktualisieren:

    relution:
  image: relution/relution:5.35.4

  2. Anschließend auf die letzte veröffentlichte 26.0.x-Version:

    relution:
  image: relution/relution:26.0.3

    Relution starten und warten, bis der Server vollständig hochgefahren ist.

  3. Nach erfolgreichem Update kann wieder auf latest gestellt werden, um automatisch die aktuellste Version zu nutzen:

    relution:
  image: relution/relution:latest

Linux und Windows (nativ)

Für native Installationen unter Linux und Windows gilt der gleiche Ablauf wie bei Docker:

  1. Update auf Relution 5.35.4
  2. Update auf Relution 26.0.3; Relution starten und warten, bis der Server vollständig hochgefahren ist
  3. Update auf die aktuellste Version (latest)

Relution 5.35.4 benötigt Java 17, ab Relution 26.0 ist Java 21 erforderlich. Vor dem Update auf Relution 26.0.3 wird daher Java 21 installiert; unter Windows muss JAVA_HOME anschließend auf die neue Java-Installation zeigen (siehe Bekannte Fehlermeldungen →).

Downloads: