MyCoRe Logo
Deutsch English
2024.06

Migration MyCoRe LTS 2023.06 nach 2024.06

Diese Seite fasst Systemanforderungen für die Nutzung des MyCoRe LTS 2024.06 und die Migration von Version 2023.06 zu 2024.06 zusammen.

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.6 oder höher
  • SuSE SLES 15.6 oder höher
  • Ubuntu 24.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 9.8.1 oder höher
  • eine hibernate-fähige relationale Datenbank wie PostgreSQL 16 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
  • Wegfall der persistence.xml (MCR-3031)
    • die Datenbank wird jetzt vollständig über Properties konfiguriert
  • Backend
    • Das JPA-Model für Zugriffsschlüssel wurde um das Feld uuid erweitert.
      Deshalb muss die Tabelle MCRAccessKey um die Spalte uuid mit dem Type UUID ergänzt werden. Das Schema kann automatisch über MCR.JPA.Hbm2ddlAuto=update aktualisiert werden.

... 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 jetzt konfigurierbar.

    Bisher wurden folgende in einer typischen Anwendung Dateien an folgenden Orten in Betracht gezogen:

    1. Developer-Overlay (falls konfiguriert)
    2. Unterverzeichnis resources des Konfigurationsverzeichnisses
    3. Inhalt von geladenen JAR-Dateien im Unterverzeichnis lib des Konfigurationsverzeichnisses
    4. Verzeichnis, in das die Dateien der Webapplikation beim Starten durch Tomcat oder Jetty extrahiert werden (nur Web-Ressourcen, Dateien aus geladenen Modulen werden während des Starts der Webapplikation nach MyCoRe-Modul-Priorität hierhin kopiert, durch das WCMS geänderte Dateien werden während des Starts der Webapplikation und bei Änderungen während der Laufzeit der Webapplikation hierhin kopiert) und 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)
    5. Inhalt von sonstigen geladenen JAR-Dateien (typischerweise JAR-Dateien, die bereits in der WAR-Datei waren, ggf. nach in web.xml definierter Reihenfolge)
    6. Von Java bereitgestellte Inhalte (per ClassLoader#getResources), sofern noch nicht vorher berücksichtigt (erster Treffer, nach Reihenfolge, in der die JVM diese ausgibt)

    Dateien aus geladenen Modulen werden nun beim Start der Webapplikation nicht mehr in das Verzeichnis, in das die Dateien der Webapplikation beim Starten durch Tomcat oder Jetty extrahiert werden, kopiert. Auf das Kopieren der vom WCMS veränderten Dateien beim Start der Webapplikation und bei Änderungen während der Laufzeit der Anwendung in dieses Verzeichnis wird ebenfalls verzichtet. Beide Mechanismen wurden ersatzlos entfernt, da sie nicht mehr benötigt werden.

    Es wird zudem standardmäßig nun eine vereinfachte und konsequenter durchgesetzte Reihenfolge verwendet:

    1. Developer-Overlay (falls konfiguriert)
    2. WCMS-Unterverzeichnis (data/save/webpages) des Konfigurationsverzeichnisses (nur Web-Ressourcen, vom WCMS geänderte Dateien werden hier gespeichert)
    3. Unterverzeichnis resources des Konfigurationsverzeichnisses
    4. Verzeichnis, in das die Dateien der Webapplikation beim Starten durch Tomcat oder Jetty extrahiert werden (nur Web-Ressourcen)
    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 und ggf. in web.xml definierter Reihenfolge)
    7. Von Java bereitgestellte Inhalte (per ClassLoader#getResource)

    Wer jedoch eine Reihenfolge bevorzugt, die sich eher an dem Verhalten älterer MyCoRe-Versionen orientiert, kann mit folgender Einstellung zu einer alternativen Reihenfolge wechseln: 

    1

     MCR.Resource.Resolver.SelectedProvider=legacy

    Typischerweise sind keine Migrationsschritte notwendig. In den folgenden Fällen kann dies aber der Fall sein:

    1. Bisher wurden JAR-Dateienm im Unterverzeichnis lib des Konfigurationsverzeichnisses und JAR-Dateien unterschiedliche behandelt und priorisiert. Jetzt werden alle JAR-Dateien gleich behandelt. Wer auf diese Unterscheidung angewiesen ist, kann entweder die genannte legacy-Reihenfolge verwenden, oder muss eine eigene Reihenfolge definieren.
    2. Wer seiner Anwendung einzelne Dateien über den Klassenpfad (java -cp path/to/resource.txtcode>) übergibt und damit Dateien, z.B. aus MyCoRe-Modulen, überschreiben will, seine Anwendung umstellen (z.B. indem diese Dateien der Anwendung stattdessen als eigenes Modul mit entsprechender Priorisierung bereitgestellt werden).
    3. Wer auf einen der Mechanismen angewiesen ist, mit dem Dateien in das Verzeichnis, in das die Dateien der Webapplikation beim Starten durch Tomcat oder Jetty extrahiert werden, kopiert werden, muss Alternativen hierzu finden. Je nach Anwendungsfall kann z.B. eine eigene Strategie zum Auffinden von Ressourcen implementiert werden.

    Potenziell kann es 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.

    Wird in den eigenen Java-Klassen auf Ressourcen zugegriffen, so sollten die Ressourcen immer mit dem neuen Mechanismus geladen werden. Hierzu muss die Klasse MCRResourceResolver verwendet werden. Insbesondere bei der Migration von bestehendem Code kann zudem die Klasse MCRResourceHelper hilfreich sein, die eine API anbietet, die sich mehr an klassischem MyCoRe-Code orientiert. Es müssen insbesondere die folgenden Methodenaufrufe ersetzt werden:

    Alter Aufruf Neuer Aufruf
    Class#getResource MCRResourceHelper#getResourceUrl
    Class#getResourceAsStream MCRResourceHelper#getResourceAsStream
    ClassLoader#resources kein Pendant
    ClassLoader#getResource MCRResourceHelper#getResourceUrl
    ClassLoader#getResources kein Pendant
    ClassLoader#getResourceAsStream MCRResourceHelper#getResourceAsStream
    ServletContext#getResource MCRResourceHelper#getWebResourceUrl
    ServletContext#getResourcePaths kein Pendant
    ServletContext#getResourceAsStream MCRResourceHelper#getWebResourceAsStream

  • 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

    <dependency>
  <groupId>org.bouncycastle</groupId>
  <artifactId>bcprov-jdk18on</artifactId>
  <version>1.80</version>
</dependency>

    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;

    Um weiter mit der SHA256 Verschlüsselung zu arbeiten, kann das folgende Property gesetzt werden:

    1

     MCR.User.PasswordCheck.SelectedStrategy=sha256

  • 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-3209 wurden die ORCID-API Endpunkte teilweise verändert.

    Der Endpunkt /api/orcid/v1/object-status/v3/{objectID} wurde in member und public aufgeteilt.
    So kann der Status explizit mittels /api/orcid/v1/public/{orcid}/works/object/{objectId} über die öffentliche ORCID API abgefragt werden. Mit /api/orcid/v1/member/{orcid}/works/object/{objectId} kann der Status über die ORCID Member API abgefragt werden.

    Ebenfalls hat sich das resultierende JSON verändert:
    mit own wird ggf. der Put-Code für das Objekt, das über die Anwendung erstellt wurden, angegeben.
    other gibt ein Array mit Put-Codes von dem Objekt wieder, die nicht von der Anwendung erstellt wurden.

    Der Pfad zum Erstellen eines Objekts wurde auf /api/orcid/v1/member/{orcid}/works/object/{objectId} geändert.

    Der Endpunkt zum Revoken einer ORCID ist nun /rsc/orcid/oauth/{orcid} und passiert mit einem HTTP-DELETE-Request.

    Die Methode revokeORCID in orcid-auth.js wurde umbenannt in revokeOrcidOAuth.


  • 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" />

Silvio Hermann Robert Stephan Jens Kupferschmidt - 13.06.2025