Aktualisierung von Drupal 9 auf Drupal 10 – Teil 1, die Vorbereitungen

In dieser zweiteiligen Artikelserie geht es um die Aktualisierung von Drupal 9 auf Drupal 10. Eine solche habe ich unlängst für die Website epicenter.academy durchgeführt, die ich 2022 entwickeln und seither technisch betreuen darf.

Drupal haftete in der Vergangenheit wohl nicht ganz unbegründet der Ruf holpriger Upgrades von Hauptversionen an. Aber das Drupal-Team hat in dieser Hinsicht wirklich Verbesserungen zustande gebracht. Selbst wenn es noch nicht so einfach von der Hand geht wie bei WordPress, so ist das Update mit guter Planung und strukturierter Vorgehensweise kein Problem.

Zu aller erst sei gesagt, dass bereits eine sehr gute offizielle Anleitung zur Verfügung steht.

Im Falle von epicenter.academy ging die Aktualisierung in drei Phase von statten:

• Phase 1: Vorbereitung in der lokalen Entwicklungsumgebung
• Phase 2: Test des Updates auf gespiegelter Seite
• Phase 3: Update der Produktionsumgebung

Dieser Artikel befasst sich mit Phase 1 während sich ein gesonderter Artikel mit Phase 2 und 3 befasst.

Phase 1: Vorbereitung in der lokalen Entwicklungsumgebung

Wie bereits oben erwähnt, steht bereits ein sehr guter Leitfaden zur Verfügung. Dieser Artikel soll ihn nicht ersetzen, sondern einfach eine zusätzliche Sichtweise darauf bieten, um da und dort vielleicht noch ein paar nützliche Details zu ergänzen.

Update auf Drupal 9.5.7

Am Anfang des Prozesses steht das Update auf die letzte zur Verfügung stehende Version des 9.x Versionsstranges, nämlich 9.5.7. Für epicenter.academy war dies ohnehin schon der Fall.

Darum konnte ich gleich damit starten, die Zusatzmodule auf den neuesten Stand zu bringen.

Update der externen Module

Kleine Anmerkung: Freilich werden Sicherheitsupdates immer prompt eingespielt. Handelt es sich jedoch um reine Feature-Releases, wird in der Regel gewartet bis wieder ein Schwung von Modulen gleichzeitig aktualisiert werden kann.

Für die gegenständliche Website standen für die Module layout_builder_styles, svg_image und h5p Aktualisierungen bereit. Verwaltet man seine Drupalinstanz mit composer, geht dies ganz einfach mit composer require vonstatten. Dabei gibt man jeweils die gewünschte Versionsnummer an, z.B.: composer require svg_image:^3.0.

Bevor man ein Modul aktualisiert, muss man sich natürlich immer vergewissern, ob die neueste Version bereits mit Drupal 10 kompatibel ist. Glücklicherweise war das für epicenter.academy überall der Fall.

Generell empfiehlt es sich, einen eigenen git-Branch, z.B. namens drupal-10-upgrade, zu erstellen und in diesem die Veränderungen nach und nach zu committen. Ebenfalls ratsam ist es, sich schon in der lokalen Entwicklungsumgebung vor neuralgischen Schritten Backups des lokalen Git-Repositories und der lokalen Datenbank zu erstellen.

Dieser Vorgehensweise folgend, entstanden mit den Upates der externen Module drei neue Commits.

Aktualisierung der Themes

Der nächste Schritt ist der Wechsel weg von deprecated Themes hin zu Themes, die auch noch in Drupal 10 unterstützt werden.

Anders als in WordPress gibt es in Drupal die Unterscheidung zwischen Admin- und Front-end Themes. Da unsere Website ein maßgeschneidertes Front-end Theme verwendet, gab es an dieser Stelle nicht anderes zu tun, als das veraltete Bartik Theme zu deinstallieren. So wie bei anderen Core Themes und Modulen meint man mit Deinstallieren nicht wirklich die Entfernung der entsprechenden Code-Dateien. Nein, obwohl es in der Adminoberfläche in beiden Fällen stets "uninstall" (oder ähnlich) genannt wird, ist es in Wahrheit lediglich ein Deaktivieren, das sich in einem geänderten oder gelöschten Flag in core.extensions.yml und ein paar verschwundenen Konfigurationsdateien manifestiert.

Übrigens: nach jedem Schritt (ein Schritt ist zum Beispiel eben das Deinstallieren des Bartik Themes) sollte die Konfiguration mit drush exportiert werden. Etwaige Änderungen werden dann einfach mit den Modifikationen in core.extensions.yml in einem Git-Commit zusammengefasst.

Ähnliches wie Bartik widerfuhr dem bis dato im Einsatz stehenden Admin-Theme Seven. Bevor dies jedoch entfernt werden konnte, war es notwendig, es durch das neuere Claro Theme abzulösen. Schließlich können noch aktive Themes selbsterklärend nicht einfach deinstalliert werden. Erst in einem zweiten Schritt war die "Deinstallation" des nun inaktiven Seven Themes möglich.

Drei weitere Git-Commits waren somit hinzugekommen.

Update oder Entfernen von Core Modulen

Nachdem externe Module und Themes fit für Drupal 10 gemacht wurden, steht ein unter Umständen etwas schwieriger Brocken bevor – das Upgraden der Core Module.

Übrigens, mit allem, was im Namen den Zusatz "Core" trägt, ist etwas gemeint, dass Drupal im Kern (zu Englisch "Core") schon mitbringt. Wie bei den Themes hat sich das Drupal-Team auch bei den Core Modulen dazu entschlossen, manche auslaufen zu lassen und nicht mehr im Kern von Drupal 10 mitzuliefern – oder wie beim gleich folgenden ein grundlegendes Update zu vollziehen.

CKEditor 4 vs. CKEditor 5

Die Rede ist von CKEditor – einem Modul das über viele Jahre in Version 4 eingesetzt wurde. CKEditor ist ein sogenannter Rich Text Editor, um in Drupal Content zu schreiben und mannigfaltig zu formatieren. Dabei muss man wissen, das der Editor nicht von Drupal selbst, sondern vom gleichnamigen Unternehmen beigesteuert wird. Version 4 wird leider nicht mehr gewartet, weshalb der Sprung auf die aktuelle Version 5 notwendig wurde.

Das Problem ist an sich nicht das Update auf CKEditor 5, sondern sogenannte Plugins. Mit Plugins sind Erweiterungen gemeint, die den Funktionsumfang des Editors ergänzen. Genau an dieser Stelle liegt die Krux, denn Version 5 der Software wurde von Grund auf neu geschrieben – im Fachjargon auch Rewrite genannt. Da sich unter der Haube so ziemlich alles geändert hat, haben CKEditor Plugins, die in Modulen verpackt in Drupal installiert werden können, die Schwierigkeit, auf die völlig neuen Schnittstellen umzustellen. Aus diesem Grund dürfte es auch eine Extra-Seite auf drupal.org geben, die den Status bekannter CKEditor-Plugins diesbezüglich sammelt.

Bei epicenter.academy stellte dies tatsächlich eine Herausforderung dar, denn die Seite verwendet das Tooltip-Modul, das auf besagter Seite richtigerweise als noch inkompatibel geführt wird. Zwar gibt es in der Community durchaus Bestrebungen das Modul wieder fit für Version 5 des Editors zu bekommen, aber bislang waren die Bemühungen nicht von Erfolg gekrönt.

Prinzipiell standen folgende Lösungswege zur Auswahl:

• Auf das als externes Modul CKEditor 4 zurückzugreifen.
• Auf die Tooltip-Funktionalität eine Weile zu verzichten bis das Tooltip-Modul hoffentlich mit dem CKEditor 5 kompatibel gemacht wurde.
• CKEditor 4 LTS (Long Term Support) zu lizenzieren.

Option 2 hat naturgegeben einen ungewissen zeitlichen Horizont. Freilich könnte man auch selbst versuchen, sich in die Entwicklung einzubringen. Allerdings ist die Einarbeitung in eine solch komplexe Software nicht zu unterschätzen.

Erstere Option hat wiederum einen entscheidenden Nachteil: Der im Modul verpackte CKEditor 4 erhält keine Sicherheitsupdates mehr. Zwar könnte man davon ausgehen, dass nach all den Jahren die Software relativ frei von Lücken sein müsste. Verlassen kann man sich darauf jedoch nicht, selbst wenn man sich die Mühe machen würde, den Code selbst zu analysieren.

Mit der letztgenannten Option gibt es einen durchaus gangbaren Ausweg. Die Firma hinter dem beliebten WYSIWYG-Editor offeriert eine Long Term Support Version. Die Preise erfährt man allerdings nur auf Anfrage.

Auf diese konnte im Falle von epicenter.academy erfreulicherweise verzichtet werden, denn das Tooltip-Modul erfüllt auch unter Drupal 10 und CKEditor 5 seine Funktionalität – zumindest für die Besucher der Seite.

Lediglich bei der Bearbeitung der Inhalte im Admin-Bereich muss auf eine wenig Komfort verzichtet werden. Und zwar ist es über den Source-Bearbeitungsmodus möglich, weiterhin das zu tun, was das Tooltip-Modul sonst über einen schönen Dialog tut, nämlich das Setzen eines data-tooltip-Attributs für die Wörter, die einen Tooltip erhalten sollen. Diese HTML-Attribute werden vom Tooltip-Modul weiterhin brav im Front-end über JavaScript in entsprechende Tooltips umgewandelt.

Mein Versuch CKEditor4 zu deinstallieren scheiterte aber trotzdem. Grund ist, dass das Tooltip-Modul weiterhin CKEditor in Version 4 als Composer-Abhängigkeit deklariert. Somit verwendet die Drupal-Installation zwar das nun oben genannte externe Modul, das CKEditor 4 kapselt, allerdings ist dieser nicht mehr als Editor für die verschiedenen Textfeldtypen zugeordnet. Damit ist CKEditor 4 zwar formal noch installiert, um die Composer-Abhängigkeit des Tooltip-Moduls zu befriedigen, ansonsten aber nicht mehr im Einsatz. Daraus resultierende Sicherheitswarnungen müssen bei der Wartung einstweilen ignoriert werden.

Deinstallation der Module Color und RDF

Mit dieser Lösung war wie bei der Tour de France die Königsetappe geschafft und der Rest der Vorbereitungen glich dem gemütlichen Ausrollen ins Ziel.

Dies beinhaltete unter anderem das Deinstallieren der in Drupal 10 nicht mehr vorhandenen Core Module Color und RDF.

Eigenen Code als kompatibel mit Drupal 10 deklarieren

Weiters musste das von mir maßgeschneiderte Front-end Theme namens epicademy formal als kompatibel mit Drupal 10 deklariert werden. Dafür war nichts mehr nötig, als in der Datei epicademy.info.yml den Schlüssel core_version_requirement auf core_version_requirement: ^9 || ^10 zu setzen.

Upgrade Status Modul

Wie in der offiziellen Anleitung empfohlen, installierte ich temporär auch das Upgrade Status Modul, das beim Scan meiner lokalen Drupal-Instanz auf Anhieb 100 % Kompatibilität anzeigte.

Upgrade auf Drupal 10 – das Ziel ist erreicht

Das Upgrade auf Drupal 10, wie immer auch in der offiziellen Anleitung beschrieben, stellte den Abschluss der Vorbereitungen dar.

Somit wurde die lokale Instanz der Seite zwar mit etwas Aufwand aber quasi anstandslos auf Drupal 10 gebracht.

Die Aktualisierung der Produktivseite habe ich in Teil 2 beschrieben.