Protokoll eines Contao Updates:
Von 3.5 auf 4.4 LTS

26. Juni 2019 von Dennis Erdmann

Seit Monaten führen wir für unsere Agenturkunden Contao Updates durch. Und auch nach dem offiziellen Support-Ende von Contao 3.5 gibt es ein paar Installationen, die wir aktualisieren müssen. Wie das bei uns abläuft und welche Probleme dabei auftreten können haben wir in diesem Beitrag zusammengefasst.

Dieser Beitrag ist anders als unsere normalen Logbuch-Einträge. Denn zum jetzigen Stand (26.06.2019) ist er noch gar nicht fertig. Stattdessen möchte ich mit diesem Beitrag den Update-Prozess dokumentieren und werde den Beitrag in regelmäßigen Abständen ergänzen.

Das bedeutet für dich, du kannst beinahe live mitverfolgen, wir das Contao Update durchführen.

Die Ausgangssituation: Eine Contao 3.5 Installation auf Contao 4.4 LTS aktualisieren

Von einer Agentur aus dem Ruhrgebiet haben wir den Auftrag erhalten, eines ihrer Kundenprojekte von Contao 3.5 auf die aktuelle LTS Version 4.4 zu aktualisieren. Wir haben das Projekt zwar nicht aufgesetzt, aber letztes Jahr übernommen und hier und da Fehler behoben sowie Anpassungen vorgenommen.

Die Website ist zweisprachig angelegt und hat relativ viele Contao Extensions im Einsatz, darunter auch Custom Catalog, um Produkte darzustellen, EFG um Bestätigungsmails zu versenden und Anfragen in der Datenbank zu speichern und ein paar Erweiterungen, um zum Beispiel wow.js für Animationen zu verwenden oder um PDFs zu gestalten.

Die größten Sorgen bereiten mir aktuell Custom Catalog und die Erweiterungen, die nicht mehr gepflegt werden, bzw. für die es keinen gleichwertigen Ersatz gibt. Hier werden wir in den nächsten Tagen testen, was nach dem Update auf Contao 4.4 noch funktioniert.

Da die Website zu umfangreich ist, um sie mal schnell an einem Nachmittag zu aktualisieren und zu testen, haben wir uns dazu entschlossen, das Update auf mehrere Tage zu verteilen.

Tag 1: Contao Installation und Einrichtung

Im Gegensatz zu bisherigen Contao Updates, z.B. von 2 auf 3 oder von 3.3 auf 3.5 ist es nicht mehr möglich einen Update-Service auszuführen. Es gibt auch (meines Wissens nach) kein Script, dass einem die Portierung einer Contao 3 Version abnimmt.

Deswegen starten wir für das Update mit einer frischen Contao 4 Installation in einer separaten Entwicklungsumgebung. Eine separate Entwicklungsumgebung deshalb, weil die Website aktuell bei Mittwald gehostet wird und wir bei Mittwald nur die PHP-Version pro Paket und nicht pro Domain einstellen können.

Da die alte Website zwingend PHP 5.6 benötigt, haben wir eine neue Entwicklungsumgebung mit PHP 7.3-latest CGI angelegt. CGI deshalb, weil wir bei einem vorherigen Projekt bei Mittwald feststellen mussten, dass Contao in einer FPM-Umgebung Imagick vermisst. Bei CGI-Versionen besteht bei Mittwald das Problem nicht. (Stand 26.06.2019)

Datenbank und Dateien kopieren

Nachdem Composer alle Dateien kopiert hat und zum Aufruf des Installtools auffordert, erstellen wir stattdessen zunächst ein Backup von der Contao 3.5 Installation. Aus diesem Backup benötigen wir den Datenbank-Dump, den wir in die neu angelegte Datenbank importieren.

Außerdem kopieren wir die Dateien aus den files und templates Ordnern in unsere neue Contao 4 Installation. Erst jetzt führen wir das Installtool aus und hinterlegen den Datenbank-Zugang. Bei der anschließenden Datenbankaktualisierung achten wir darauf, dass zunächst nur Einträge hinzugefügt und geändert werden. Die zum Löschen vorgesehenen Einträge überspringen wir erstmal, da wir nach und nach die Erweiterungen installieren werden.

Die Spannung steigt: Erster Aufruf des Frontends

Jetzt wird es spannend. Ist die Contao Installation bereits lauffähig? Oder gibt es nur die berühmte Contao-Fehlerseite? Tatsächlich sieht es auf den ersten Blick gar nicht so schlecht aus. Die Website ist zwar nackt, da keine Stylesheets und Skripte geladen werden, aber grundsätzlich funktioniert sie erstmal.

Nachdem wir die notwendigen Ordner in files auf öffentlich gestellt haben, passt auch die Darstellung. Natürlich gibt es noch die ein oder andere Abweichung: Bei der Suche hat der Button nun ein Label + Icon (vorher nur ein Icon), der Textblock im Slider ist ausgeblendet, da jQuery noch nicht geladen wird und ein paar Container haben abweichende Höhen. Aber alles in allem sieht das schon sehr gut aus.

Nach ein bisschen Recherche stellt sich heraus: Die meisten der gerade beschriebenen Fehler sind Template-Anpassungen geschuldet. Nachdem wir in der j_accordion.html5 den Pfad zu jQueryUI aktualisiert haben, wird der Slider korrekt dargestellt und auch die Maße für die Container passen nun. Da die Buttons in Formularen keine <input> mehr sind, sondern <button>, müssen wir ein neues Template anlegen. Der Punkt landet erstmal auf unserer Contao-Check-Liste, da es andere Probleme geben wird, die höhere Priorität haben werden und als erstes in Angriff genommen werden müssen.

Fazit Tag 1: Es lief besser als gedacht

Ehrlich gesagt habe ich nicht damit gerechnet, dass die Installation ohne die Erweiterungen überhaupt lauffähig wäre. Aber die richtige Arbeit kommt erst noch.

Morgen schauen wir uns die bisher verwendeten Erweiterungen an und prüfen, welche sich über den Contao Manager beziehen lassen, welche wir durch andere Erweiterungen ersetzen können und welche wir kopieren müssen, in der Hoffnung, dass diese kompatibel sind oder angepasst werden müssen.

Tag 2: Git-Versionierung und Extensions

Nachdem wir am ersten Tag eine funktionierende Grund-Installation aufgebaut haben, wollen wir uns heute um die bisher eingesetzten Contao-Erweiterungen kümmern. Aber vorher legen wir noch einen Zwischenschritt ein. Denn jetzt ist der perfekte Zeitpunkt, um das Projekt mittels Git zu versionieren.

Einrichtung Gitlab

Wir verwenden für die Git-Versionierung Gitlab in der selbstgehosteten Community Edition. Diese hat einerseits den Vorteil, dass die Daten alle auf einem Server (bei Hetzner) in Deutschland liegen, andererseits, dass wir auch das Deployment über einen eigenen Gitlab-Runner laufen lassen können.

Bisher war das Projekt aus Kostengründen nicht versioniert, was schon häufiger dazu führte, dass wir Code und Fixes nur durch ausprobieren verstehen konnten. Außerdem mussten wir händisch dokumentieren, welche Änderungen wir an welchen Dateien auf dem Entwicklungsserver gemacht haben, um diese nach erfolgreichen Tests auf Live einspielen zu können.

Mit Git gehören große Teil dieses Problems der Vergangenheit an, da wir Dateiänderungen per Knopfdruck auch auf Live veröffentlichen können (dank eines gitlab-basierten Deployments von Richard).

Nachdem wir die Contao-Installation und das Deployment in Gitlab eingerichtet hatten, konnte es nun mit der Übernahme der Contao Erweiterungen weitergehen.

Aktualisierung, Ersetzung und Übernahme der Contao Erweiterungen

Da das Projekt mit sehr vielen Contao-Erweiterungen umgesetzt wurde – insgesamt über 40 Erweiterungen – haben wir im ersten Schritt eine Excel-Tabelle angelegt. Tatsächlich wird der überwiegende Teil auch tatsächlich genutzt.

Im ersten Schritt haben wir uns jede Erweiterung einzeln angeschaut:

• Was macht die Erweiterung grundsätzlich (da wir nicht alle Erweiterungen kennen)?
• Wie wird sie im Projekt genutzt?
• Wie wichtig ist die Erweiterung für das Projekt oder könnten wir auch darauf verzichten?
• Ist sie über Composer installierbar?
• Wenn nicht, gibt es eine Weiterentwicklung der Extension von einem anderen Entwickler?
• Welche Erfahrungen haben wir mit der Erweiterung bereits sammeln können?

Aus diesen Fragen ergab sich eine Liste mit 3 Abschnitten:

1. Erweiterungen, die sich problemlos unter Contao 4 verwenden lassen sollten
2. Erweiterungen, die mit Anpassungen auch unter Contao 4 laufen sollten
3. Erweiterungen, die nicht mit Contao 4 kompatibel sind oder die große Probleme beim Contao Upate bereiten könnten

Während sich die Erweiterungen aus 1. und 2. relativ gut kalkulieren lassen, sind die Erweiterungen aus Abschnitt 3 schwer bis gar nicht zu kalkulieren. Hier haben wir mit Agentur und Kunde vereinbart, dass wir zunächst das Update durchführen, alle Erweiterungen aus Abschnitt 1 und 2 aktualisieren und für Abschnitt 3 eine Einschätzung pro Erweiterung abgeben. So kann der Kunde selbst entscheiden, wie wichtig eine Funktion für ihn zukünftig im Shop ist und die Kosten dementsprechend selbst steuern.

Installation von Contao Erweiterungen über Composer

17 der insgesamt 41 Erweiterungen ließen sich unter Contao 4 direkt über Composer bzw. den Contao Manager installieren. Und nach ersten Tests (abgesehen von der Caroufredsel-Erweiterung, bei der wir einen Flüchtigkeitsfehler beheben mussten, inkl. Pull-Request) funktionieren diese nach einem Datenbank-Update auch noch wie unter Contao 3.

Allerdings hatte ich gehofft, dass es ein paar Erweiterungen mehr sein würden.

Contao Erweiterungen, die nicht mehr benötigt werden

Mittlerweile haben wir auch eine Liste mit Extensions zusammengestellt, die nach aktuellem Stand nicht mehr benötigt werden. Darunter gehören zum Beispiel Erweiterungen, die ein Youtube-Element zur Verfügung stellen, für Spalten-Layouts installiert aber nicht verwendet wurden und für den Import und Export von Inhalten zur Übersetzung der Website.

Insgesamt 7 Erweiterungen können nach aktuellem Stand ersatzlos gelöscht werden. 

Fazit Tag 2: Die wirklich großen Probleme kommen noch

Die Einrichtung von Gitlab und Deployment hat relativ lange gedauert. Eigentlich haben wir dafür bereits ein fertiges Setup, da aber so viele Extensions händisch gepflegt werden müssten, wollte ich sicher gehen, dass sich diese über git versionieren lassen.

So blieb zum Testen der Extensions nicht mehr so viel Zeit. Aber wie heißt es so schön: Immer etwas für morgen übrig lassen. 

Tag 3: Manuelle Installation von Extensions

Heute geht es um die übrigen Erweiterungen, die sich nicht über Composer installieren lassen und nicht durch kompatible Extensions ersetzt werden können. Beim Durchstöbern der überflüssigen Datenbank-Einträge, die das Installtool vorschlägt zu löschen, haben wir noch 2 weitere Extensions entdeckt, die über den Contao Manager installiert werden können:

• conditionalforms
• wf_extendedbreadcrumb

Zweitere ist zwar nicht offiziell kompatibel, es gibt aber einen Branch compat/contao-4, der zumindest einen Versuch wert ist. Und tatsächlich scheint die Erweiterung fehlerfrei zu funktionieren.

Damit müssten jetzt wirklich alle Erweiterungen installiert sein, die zukünftig automatisch aktualisiert werden können. Kommen wir also zu den Erweiterungen, die wir durch Copy and Paste in system/modules/ versuchen zum Laufen zu bringen.

Manuelle Installation von Erweiterungen

Folgende Erweiterungen sind nun noch übrig geblieben:

• 2 Erweiterungen zur Verwendung von wow.js
• EFG (soll ersetzt werden durch Notification Center und evtl. Leads)
• Custom Catalog und Custom Elements

Manuelle Installation Wow.js Erweiterungen

Bevor wir wirklich die Erweiterungen manuell installieren, hatte ich mich nochmal vergewissert, ob sich die Erweiterung nicht durch eine andere ersetzen ließe. Hier gibt es zum Beispiel contao-wowjs von inspiredminds. Und für die meisten Fälle würde die Erweiterung auch ausreichen. Allerdings gibt es bei der alten Erweiterung noch die Möglichkeit, ein Start- und End-Element zu verwenden, was bei der Alternative von inspiredminds leider fehlt.

Deswegen werden wir hier den Weg des geringsten Widerstands gehen und die bestehende Extension weiterverwenden. Bei der anderen wow.js Erweiterung haben wir anhand der leeren Tabellenspalten feststellen können, dass diese glücklicherweise gar nicht eingesetzt wurde. So kann auch diese Erweiterung gelöscht werden.

EFG Erweiterung ersetzen

Die Erweiterung Extended Form Generator, kurz EFG wurde lange Zeit und von vielen Contao-Nutzern eingesetzt. Obwohl die Weiterentwicklung schon zu 3.2 Zeiten eingestellt wurde, gab es irgendwie immer jemanden, der Fehler behoben und die Erweiterung wieder kompatibel gemacht hat.

Aber mit dem Wechsel auf Contao 4 ist nun endgültig Schluss. Das Problem am EFG ist, dass die Erweiterung sich an so vielen Stellen einklinkt, dass es gar nicht so leicht ist, festzustellen, welche Funktionen alle tatsächlich genutzt werden. 

Offensichtliche Funktionen sind:

• Mail und Bestätigungsmail individuell gestalten
• Speichern der Formulardaten in der Datenbank

Weniger offensichtlich hingegen sind die zusätzlichen Formularfelder, die der EFG mitbringt. So gibt es zum Beispiel ein Select-Auswahl-Feld, mit dem sich beliebige Inhalte aus der Datenbank auswählen lassen. Oder ein Feld, mit dem sich Bilder dem Formular hinzufügen lassen.

Deswegen verbrachten wir den Rest des Tages damit, die insgesamt 27 Formulare auf EFG-Einstellungen zu prüfen. Am Ende hatten wir die Gewissheit: Alle Funktionen lassen sich mit dem Notification Center und Leads von terminal42 abbilden.

Tag 4: Aktualisierung von Custom Catalog und Custom Elements

Nachdem alle anderen Erweiterungen über Composer oder manuell installiert wurden, bleibt nun noch das Update von Custom Catalog und Custom Elements. Vor dem Update war das Backend zerschossen, im Frontend wurde zwar die Produktliste angezeigt, die Produktdetailseite erzeugte allerdings einen Fehler 404.

Nachdem wir die entsprechenden Ordner 1:1 durch die neueste Version ersetzt hatten, fällt auf den ersten Blick das Backend auf. Hier werden die einzelnen Kataloge nun wieder korrekt dargestellt, auch die Icons funktionieren wieder.

Im Frontend funktioniert weiterhin die Produktliste und die Produktdetailseite erzeugt weiterhin einen Fehler 404. Nach längerer Recherche finden wir heraus, dass die deutsche Version deswegen nicht funktioniert, da Deutsch der Fallback-Eintrag ist. Zwei Häkchen in den Systemeinstellungen unter CustomCatalog-Einstellungen und die Produktdetailseite funktioniert auch wieder.

Folgende Probleme bleiben nach dem Update offen:

• Produktliste: Die Reihenfolge der Attribute wird nicht mehr berücksichtigt
• Produktdetailseite: Attribute für Title und Description werden ignoriert
• Die Verknüpfung der deutschen und englischen Variante eines Produktes funktioniert nicht 100%ig
• eine Such-Erweiterung, die auf CC aufbaut, funktioniert nicht mehr

Hier werden wir vorab eine Einschätzung zur Behebung dieser Probleme abgeben und diese in Absprache priorisieren.

Auch wenn dieser Tag in der Zusammenfassung relativ kurz aussfällt, haben wir über 4 Stunden an der Aktualisierung und Kontrolle gearbeitet und werden vermutlich noch 1-2 Stunden für die Aufwandseinschätzung benötigen.

Tag 5: Layoutanpassungen und inhaltliche Anpassungen

Während der eine Teil prüft, mit welchen Kosten die Fehlerbebung von Custom Catalog verbunden ist, arbeitet der andere Teil an der Layoutanpassung und den inhaltlichen sowie technischen Anpassungen. So müssen zum Beispiel alte Youtube-Elemente durch die contaoeigenen Youtube-Elemente ersetzt werden, die Suchleiste muss in der Darstellung wieder angepasst werden und individuelle Download-Icons müssen wieder angezeigt werden.

Da die Website zweisprachig angelegt ist und Videos an allen möglichen Stellen vorhanden sein könnten, nehmen wir den Umweg über die MySQL-Datenbank und prüfen wieviele Inhaltselemente vom Typ html5 vorhanden sind.

Nach etwa 2 Stunden sind alle Elemente durch Videos bzw. Youtube-Videos ersetzt. Parallel haben wir die letzten Tests vorgenommen, weitere Optimierungsvorschläge erstellt und Kalkulationen für die noch offenen Tickets vorgenommen.