Migration MyCoRe LTS 2023.06 nach 2024.06

Systemanforderungen MyCoRe LTS 2024.06

Für den Betrieb einer MyCoRe-Anwendung unter LTS 2024.06 sind folgende Voraussetzungen zu erfüllen:

Betriebssystem

MyCoRe LTS 2024 ist auf diesen Betriebsystemen im Einsatz. Höhere Versionen sollten kein Problem darstellen.

• Open SuSE Leap 15.4 oder höher
• SuSE SLES 15.4 oder höher
• Ubuntu 20.04 LTS
• CentOS 8
• RHEL 8
• Windows 10 für Test- und Entwicklungssysteme

Standardsoftware

Zur Arbeit mit MyCoRe LTS 2024 sind folgende Softwarekomponenten erforderlich bzw. empfohlen. Diese sind alle von Drittanbietern und im Normalfall in den Distributionen enthalten.

• Java 21 (OpenJDK) (muss ggf. extern nachinstalliert werden)
• Tomcat 10.1.x bzw. Jetty 11.x (alternativ ein System mit Unterstützung von Servlet-6.0 und JakartaEE)
• SOLR 8.11.2 oder höher
• eine hibernate-fähige relationale Datenbank wie PostgreSQL 10 oder höher , MySQL/Maria-DB 10 oder höher, DB2; für Testzwecke genügt auch die integrierte Datenbank H2
• Git 2.26 oder höher
• Apache Maven 3.6.3 oder höher

Neuerungen

... die eine Migration erforderlich machen

• Java 21 als Minimal-Voraussetzung (MCR-3028, MCR-3029)
• OCFL Filesystem (MCR-3126)
  • size als fixity ergänzt
• Absolute Pfade in XSLT1-Includes verwenden (MCR-3088, MCR-3055)
  • Auf Warnungen im Log achten und eigene Stylesheets anpassen
    (z.B.: WARN guest MCRURIResolver: The Stylesheet jar:file:[...].xsl which only works with an old absolute include mechanism. Please change the include to relative!)
• XSLT3-Migration
  • XSLT1(Xalan)-Legacy (MCR-3087)
• Wegfall der persistence.xml (MCR-3031)
  • die Datenbank wird jetzt vollständig über Properties konfiguriert

... die ohne Migration eingeführt wurden

• Rate-Limiting-URI-Resolver
• ggf. OCFL Store for Derivate
• allow selection of XSLT processor when using MCRXslStyeResolver(MCR-3087)
• Benutzer-Suche sucht nun auch in Attributen
• SOLRJ 9.6 Clients
  • Varianten mit Apache HTTPClient deprecated, Alternativen basieren Java-internen HTTPClient (noch neu und fehleranfällig) oder JettyLibrary (untersützt nur HTTP2 und läuft deshalb nur mit Solr Server 8 oder aktueller (Prüfen!)
• Support für Solr-Cloud-Installationen und externen Tika-Server
  • MCR-3113-15: SolrCloud-Support(MCR-3113)
  • Dedizierter TikaServer (MCR-3113)
  • paralleles Indizieren in mehreren Kernen (MCR-3115)
  • Verwendung von SOLR Nutzern (Logins) für Administrative Anfragen und Suchanfragen
• ggf. SOLR 9 Server als Empfehlung?
  • SOL 10.0.alpha ist released. Es besteht die “Gefahr”, dass SOLR 9 im Laufe des nächsten Jahres zum LTS wird und damit der Update-Support für Version 8 einstellt wird.)

aus dem Code entfernt

• ToDo: ergänzen

Migrationsschritte

• Mit MCR-2881 wurden die Art und Weise, wie MyCoRe Ressourcen ausfindig macht und ausliefert, komplett überarbeitet. Zuvor wurden nur ausgewählte Arten von Dateien (z.B. XML- oder XSL-Dateien) als Ressourcen angesehen. Für andere Arten von Dateien (z.B. Bilder) mussten eigenen Strategien entwickelt werden, um diese zu lokalisieren, auszuwählen und auszuliefern. Nun können alle Arten von Dateien gleichartig als Ressourcen verwendet werden. Die Orte, an denen nach solchen Dateien gesucht wird (z.B. Developer-Overlay, Konfigurationsverzeichnis, Bibliotheken) und deren Priorisierung (z.B. nach MyCoRe-Modul-Priorisierung) wird jetzt konsequent und gleichartig genutzt. Zudem ist die Auswahl dieser Orte nun konfigurierbar.

  Bisher wurden folgende Orte in Betracht gezogen:

  1. Developer-Overlay (falls konfiguriert)
  2. Verzeichnis, in das die Dateien der Webapplikation beim Starten durch Tomcat oder Jetty extrahiert werden (nur Web-Ressourcen, durch das WCMS geänderte Dateien werden während des Starts der Webapplikation und bei Änderungen während der Laufzeit der Webapplikation hierhin kopiert)
  3. Unterverzeichnis resources des Konfigurationsverzeichnisses
  4. Inhalt von geladenen JAR-Dateien im Unterverzeichnis lib des Konfigurationsverzeichnisses (nach MyCoRe-Modul-Priorität)
  5. Unterverzeichnis WEB-INF/classes des Verzeichnisses, in das die Dateien der Webapplikation beim Starten durch Tomcat oder Jetty extrahiert werden (typischerweise Dateien, die bereits in der WAR-Datei waren)
  6. Inhalt von geladenen JAR-Dateien im Unterverzeichnis WEB-INF/lib des Verzeichnisses, in das die Dateien der Webapplikation beim Starten durch Tomcat oder Jetty extrahiert werden (typischerweise JAR-Dateien, die bereits in der WAR-Datei waren, nach MyCoRe-Modul-Priorität)

  Auf das Kopieren der vom WCMS veränderten Dateien beim Start der Webapplikation und bei Änderungen während der Laufzeit der Anwendung wird nun verzichtet. Der Mechanismus wurde ersatzlos entfernt, da er nicht mehr benötigt wird. Zudem wird nun standardmäßig eine vereinfachte Reihenfolge verwendet:

  1. Developer-Overlay (falls konfiguriert)
  2. Unterverzeichnis data/save/webpages des Konfigurationsverzeichnisses (nur Web-Ressourcen, vom WCMS geänderte Dateien werden hier gespeichert)
  3. Verzeichnis, in das die Dateien der Webapplikation beim Starten durch Tomcat oder Jetty extrahiert werden (nur Web-Ressourcen, einige Ressourcen und durch das WCMS geänderte Dateien werden während des Starts der Webapplikation und letztere auch bei Änderungen während der Laufzeit hierhin kopiert)
  4. Unterverzeichnis resources des Konfigurationsverzeichnisses
  5. Unterverzeichnis WEB-INF/classes des Verzeichnisses, in das die Dateien der Webapplikation beim Starten durch Tomcat oder Jetty extrahiert werden (typischerweise Dateien, die bereits in der WAR-Datei waren)
  6. Inhalt von geladenen JAR-Dateien (unabhängig von deren Ort, nach MyCoRe-Modul-Priorität)

  Typischerweise sind keine Migrationsschritte notwendig.

  Wer jedoch eine Reihenfolge benötigt, die sich bezüglich des Inhalts von JAR-Dateien nach dem Verhalten älterer MyCoRe-Versionen richtet, kann mit folgender Einstellung zu einer alternativen Reihenfolge wechseln:

  1	MCR.Resource.Resolver.SelectedProvider=legacy

  Potenziell kann es auch empfehlenswert sein, eine eigene Reihenfolge zu definieren. Wenn man keinen Developer-Overlay und kein WCMS verwendet und keine Dateien im Konfigurationsverzeichnis ablegt, sondern alle relevanten Dateien in MyCoRe-Modulen vorhält, kann beim Aufruf einer Ressource z.B. auf das mehrfache Suchen im Dateisystem verzichtet werden. Da in solch einem Szenario keine Ressourcen zur Laufzeit der Applikation verändert werden können, kann zudem ein Cache konfiguriert werden. Beide Maßnahmen sorgen dafür, dass das Aufrufen von Ressourcen deutlich effizienter wird. Eine solche Anpassung kann für produktive Systeme durchaus sinnvoll sein.

  Wer in seiner eigenen Applikation bisher auf den Mechanismus angewiesen ist, mit dem ausgewählte Dateien beim Start der Webapplikation extrahiert werden, muss Alternativen hierzu finden. Je nach Anwendungsfall kann z.B. eine eigene Strategie zum Auffinden von Ressourcen implementiert werden.

• Mit MCR-2919 wurden erweiterte Möglichkeiten geschaffen, die Konfiguration von Instanzen von Java-Klassen deklarativ mit Annotationen vorzunehmen. Hierbei hat sich eine ungewollte Änderung in der Funktion der Methode MCRConfiguration2#getInstances(String) eingeschlichen.

  Sind z.B. Einträge für die Schlüssel MCRExample.foo und MCRExample.bar in der Konfiguration der MyCoRe-Anwendung vorhanden und wird die genannte Methode mit dem Wert MCRExample. aufgerufen, so sollten in der zurückgegebenen Map<String, Callable> Einträge mit den Schlüsseln foo bzw. bar vorhanden sein. Fehlerhafterweise wurden jedoch Einträge für die kompletten Schlüssel MCRExample.foo bzw. MCRExample.bar erzeugt. Mit MyCoRe 2024.06 werden nun wieder Einträge mit den eigentlich angedachten Schlüsseln foo bzw. bar erzeugt.

  Wer in seinem eigenen Java-Code die Methode Methode MCRConfiguration2#getInstances(String) nutzt, muss ggf. Anpassungen vornehmen. Wer diese Methode nicht in eigenen Java-Klassen verwendet, kann diesen Migrationsschritt ignorieren.

• Durch MCR-3053 wurden die Einstiegspunkte der Java-API zum instanziieren konfigurierter Objekte überarbeitet. Die folgenden drei Methoden sind nun als veraltet markiert und werden in einer künftigen Version von MyCoRe entfernt:

  • MCRConfiguration2#getInstanceOf(String),
  • MCRConfiguration2#getSingleInstanceOf(String),
  • MCRConfiguration2#getSingleInstanceOf(String, Class)

  Als Ersatz wurden die folgenden vier Methoden hinzugefügt, bei denen die erwartete Klasse des Rückgabewerts explizit als erster Parameter angegeben werden muss und die entweder ein Optional zurückgeben oder bei Fehlen der entsprechenden Konfiguration direkt einen Fehler werfen:

  • MCRConfiguration2#getInstanceOf(Class, String),
  • MCRConfiguration2#getInstanceOfOrThrow(Class, String),
  • MCRConfiguration2#getSingleInstanceOf(Class, String),
  • MCRConfiguration2#getSingleInstanceOfOrThrow(Class, String)

  In diesem Zusammenhang wurden alle Verwendungen dieser API in MyCoRe und MIR auf die neuen Methoden umgestellt und sichergestellt, dass die zu verwendende Klasse in einem Konfigurationswert definiert ist. Zum Beispiel wurde MCRConfiguration2.<MCRCategoryDAO>getInstanceOf("MCR.Category.DAO").orElseGet(MCRCategoryDAOImpl::new); durch MCRConfiguration2.getInstanceOfOrThrow(MCRCategoryDAO.class, "MCR.Category.DAO"); ersetzt. Zudem wurde der Konfigurationswert MCR.Category.DAO=org.mycore.datamodel.classifications2.impl.MCRCategoryDAOImpl angelegt. Dies ist für zukünftige und eigene Entwicklungen die empfohlene Herangehensweise. Wer in seiner eigenen Anwendung eine der nun als veraltet markierten Methoden verwendet, muss entsprechende Anpassungen ebenfalls vornehmen.

• Statt MCRMD5InputStream gibt es seit MCR-3096 die flexiblere Klasse MCRDigestInputStream.

  Wer die genannte Klasse in eigenem Java-Code verwendet, muss diesen anpassen. Ein MD5-Hash kann nun wie folgt erzeugt werden:

  1 2 3

  MCRDigestInputStream digestStream = new MCRDigestInputStream(inputStream, MCRMD5Digest.ALGORITHM); ...; String md5Digest = digestStream.getDigestAsHexString();

• Falls erkannt wurde, dass ein Client keine Cookies unterstützt, hat MyCoRe vor MCR-3127 die HTTP-Session verfolgt, indem die Session-ID als JSESSIONID-URL-Parameter in generierte Links eingefügt wurde. Dieser Mechanismus ist veraltet und potenziell unsicher und wurde daher ersatzlos entfernt. Zudem heißt das Cookie, in dem die Session-ID gespeichert wird, nun technologieagnostisch MCRSESSIONID.

  In eigenen XSLT-Stylesheets muss die Verwendung der Variablen $HttpSession und $JSessionID sowie die Verwendung der Templates UrlAddSession und UrlDeleteSession entfernt werden, da diese nicht mehr zur Verfügung stehen. Wer das Session-Cookie manuell auswertet, muss die Namensänderung beachten.

• Mit MCR-3137 wurde die nicht mehr zeitgemäße Art, wie MyCoRe Hash-Werte von Passwörtern speichert, modernisiert und anpassbar gemacht. Statt SHA-256 wird nun standardmäßig der Algorithmus PBKDF2 als Hash-Funktion verwendet (für diesen wird typischerweise keine zusätzliche Programmbibliothek benötigt). Eine explizite Migration ist nicht notwendig. Die gespeicherten Hash-Werte werden automatisch aktualisiert, wenn sich Nutzende das nächste Mal erfolgreich anmelden.

  Es ist jedoch sehr empfehlenswert, statt PBKDF2 den aktuell von OWASP empfohlenen Algorithmus Argon2 zu verwenden. Dazu muss der Anwendung die Bibliothek org.bouncycastle:bcprov-jdk18on zur Verfügung gestellt und folgenden Konfiguration vorgenommen werden:

  1 2 3 4 5 6 7 8 9

  MCR.User.PasswordCheck.Strategies.argon2.Class=org.mycore.user2.hash.bouncycastle.MCRArgon2Strategy MCR.User.PasswordCheck.Strategies.argon2.Enabled=true MCR.User.PasswordCheck.Strategies.argon2.SaltSizeBytes=32 MCR.User.PasswordCheck.Strategies.argon2.HashSizeBytes=64 MCR.User.PasswordCheck.Strategies.argon2.Parallelism=1 MCR.User.PasswordCheck.Strategies.argon2.MemoryLimitKilobytes=66536 MCR.User.PasswordCheck.Strategies.argon2.Iterations=8 MCR.User.PasswordCheck.SelectedStrategy=argon2

  In der aktuellen Version von MIR sind diese Anpassungen bereits enthalten. In eigenen Anwendungen sollten sie entsprechend vorgenommen werden.

  Bei erst kürzlich aufgesetzten Systemen muss gegebenenfalls ein durch Hibernate erstelltes Datenbank-Costraint entfernt werden, z.B. bei PostgreSQL mit dem folgenden Befehl:

  1	ALTER TABLE mcruser DROP CONSTRAINT mcruser_hashtype_check;

• MCR-3140 hat einen Mechanismus eingeführt, mit dem alte, nicht mehr benötigte Einträge in der Job-Queue entfernt werden können. Dies ist insbesondere für banale Jobs (z.B. Erzeugen von statisch vorberechneten Inhalten, Erzeugen von Thumbnails) interessant, die häufig ausgeführt werden und deren Ausführung nicht langfristig dokumentiert werden muss.

  Für derartige Jobs wurde eine Regel definiert und standardmäßig aktiviert, die die Einträge für erfolgreich ausgeführte Jobs am Folgetag entfernt. Diese Regel kann wie folgt deaktiviert werden:

  1	MCR.QueuedJob.Cleaner.Selectors.finishedOrdinaryJobs.Enabled=false

  Eigene Implementierungen von MCRJobAction (im Beispiel: foo.bar.FooJobAction) können wie folgt in die Liste der als banal geltenden Jobs eingefügt werden, um von der genannten Regel ebenfalls behandelt zu werden:

  1	MCR.QueuedJob.OrdinaryJobs=%MCR.QueuedJob.OrdinaryJobs%,foo.bar.FooJobAction

  Zudem gibt es vordefinierte Regeln, die die Einträge für beliebige erfolgreich oder nicht-erfolgreich ausgeführte Jobs nach 30 bzw. 90 Tagen entfernt. Diese Regeln sind jedoch nicht standardmäßig aktiviert und können wie folgt aktiviert werden.

  1 2	MCR.QueuedJob.Cleaner.Selectors.finishedJobs.Enabled=true MCR.QueuedJob.Cleaner.Selectors.failedJobs.Enabled=true

  In Anlehnung an die vordefinierten Regeln können zudem eigene Regeln definiert werden.

• Mit MCR-3200 werden keine Standardwerte mehr für die ORCID-User-Properties ausgeliefert, sofern jene nicht existieren. Damit wird ermöglicht, dass im Frontend unterschieden werden kann, ob ein User bereits Properties festgelegt hat. Dies kann beispielsweise wichtig werden, wenn sich die Standardwerte einmal ändern sollten und ein User diese nicht für sich übernommen bzw. für sich gespeichert hat. Außerdem können so einfacher weitere Properties hinzugefügt werden, denn so ist eine Abgrenzung bereits gespeicherter Properties möglich. Durch diese Umstellung müssen die Properties ggf. im Frontend anders interpretiert werden.

Datenbank(-konfiguration) anpassen

Anpassung der Spaltenlänge in MCRJobParameter-Tabelle

Falls beim Update die Datenbank nicht neu erstellt wird, ist folgende Anpassungen an den Tabellen notwendig (siehe MCR-3125):

1
2

PostgreSQL:>  ALTER TABLE mcrjobparameter ALTER COLUMN paramvalue SET DATA TYPE varchar(16384);
        H2:>  alter table mcrjobparameter alter column paramvalue varchar(16384);

H2 Migration

Auf Grund der Aktualisierung von MyCoRe auf Hibernate 6.3.x und Jakarta Persistence 3.1 muss eine bestehende H2-Datenbank auf Version 2.x geupdatet werden. Die notwendigen Schritte sind im Ticket MCR-2637 beschrieben.

H2: Konflikte beim Spaltennamen

Bei der Datenbank H2 (Version 2.x) gibt es Namenskonflikte bei einem Spaltennamen. Deshalb müssen folgende JPA-Properties gesetzt sein:

via MyCoRe-Properties

1
2

MCR.JPA.GloballyQuotedIdentifiers=true
MCR.JPA.GloballyQuotedIdentifiers.SkipColumnDefinitions=true

oder (veraltet): persistence.xml

1
2

<property name="hibernate.globally_quoted_identifiers" value="true" />
<property name="hibernate.globally_quoted_identifiers_skip_column_definitions" value="true" />