Contao CMS upgraden: Typische Probleme – und wie man sie löst

Contao Release Plan 2012-2017
Contao Release Plan 2012-2017

Das Open Source CMS Contao wird kontinuierlich weiterentwickelt. Der Relase Plan sieht vor, alle sechs Monate ein neues Release zu veröffentlichen. Das ist erfreulich für diejenigen, die sich auf neue Features freuen; es bedeutet aber auch eine Menge Arbeit für all jene, die für eine Contao-Installation verantwortlich sind, denn eine normale Contao-Version wird nur ein halbes Jahr lang gepflegt und muss dann aktualisiert werden. Lediglich die Versionen mit Long Term Support (LTS) werden zwei Jahre lang mit Bugfixes und sicherheitsrelevanten Patches versorgt.

Ende Juli 2014 läuft der Support für Contao 2.11 aus, und somit wird vielerorts das Upgrade auf Contao 3.2 LTS oder Contao 3.3 anstehen. Ich habe in den letzten Monaten eine ganze Reihe von Websites aktualisieren müssen und fasse in diesem Artikel meine wichtigsten Erfahrungen zusammen.

Backup erstellen

Ein vollständiges Backup von Datenbank und Dateisystem ist Pflicht, bevor man ein CMS-Upgrade installiert – das ist bei Contao nicht anders. Damit ist man nicht nur gegen einen GAU gewappnet (z.B. zerschossene Datenbank; gelöschte Bilder, Templates und Konfigurationsdateien), sondern kann jederzeit zum Ursprungszustand zurückkehren, wenn man mit inkompatiblen Extensions oder Stylesheet-Problemen konfrontiert wird. Noch viel entspannter kann man das Upgrade übrigens angehen, wenn man es nicht direkt auf dem Live-System durchführt, sondern auf einem Test-System.

Systemdiagnose durchführen

Contao braucht gewisse Komponenten, Konfigurationseinstellungen und Berechtigungen auf dem Webserver, damit es korrekt funktioniert, und diese Systemvoraussetzungen können über die Versionen hinweg auch einmal ändern. Es ist deshalb eine gute Idee, vor dem Upgrade das Systemdiagnose-Tool Contao Check laufen zu lassen.

Releases einzeln installieren

Grundsätzlich ist es möglich, beim Upgrade einzelne Releases zu überspringen, aber ich würde es trotzdem nicht empfehlen. Das Install Tool erkennt zwar die Version der Datenbank und führt automatisch die Aktualisierungsschritte für jede einzelne Version durch. Wenn es aber Probleme gibt, dann wird die Fehlersuche deutlich aufwändiger, weil man nicht genau weiss, welche Contao-Version dafür verantwortlich ist. Installiert man der Reihe nach jedes einzelne Minor-Release, dann sind Probleme vielleicht nicht seltener, aber wenigstens schneller eingegrenzt und besser dokumentiert.

Extensions inventarisieren, deaktivieren und aktualisieren

Wenn man nach dem Upgrade nur noch PHP-Fehlermeldungen sieht, dann ist oft nicht der Contao Core, sondern eine Extension dafür verantwortlich. Um solche zu Probleme zu lösen muss man wissen, welche Extensions überhaupt installiert sind. Sicherheitshalber überprüft man nicht nur die Erweiterungsverwaltung im Contao-Backend, sondern auch die Liste unter System > Einstellungen > Inaktive Erweiterungen und wirft zudem per FTP Client einen Blick in das Verzeichnis /system/modules/. Gerade wenn es sich um eine ältere Website handelt, kann es nämlich sein, dass hier noch Altlasten aus früheren Contao-Versionen liegen, die gar nicht in der Erweiterungsverwaltung auftauchen (weil es diese in frühen Versionen von TYPOlight/Contao noch gar nicht gab). Extensions, die man nicht benutzt und die nicht zum Core gehören, kann man bei dieser Gelegenheit gleich entsorgen.

Idealerweise klärt man vor dem Upgrade ab, ob die benutzten Extensions mit der neuen Contao-Version kompatibel sind. Gibt es dennoch Probleme, kann man aber eine Extension per FTP Client selbst dann noch deaktivieren, wenn das Contao-Backend (und damit die Erweiterungsverwaltung) nicht mehr zugänglich ist: Löschen Sie ganz einfach das entsprechende Unterverzeichnis in /system/modules/. Welche Extension der Übeltäter ist findet man oft heraus, wenn man die Fehlermeldungen ganz genau liest: PHP gibt normalerweise das fehlerverursachende Skript inklusive den kompletten Pfad aus.

Auch wenn man keine PHP-Fehlermeldungen sieht kann eine Extension für Probleme verwantwortlich sein. Ich erinnere mich an einen Fall, wo das Install Tool meldete, dass die Datenbank nicht aktuell sei – aber ein Klick auf den Button Datenbank aktualisieren zeigte keine Wirkung. Schuld war letztlich die veraltete Extension development.

Hat das Upgrade so weit geklappt, dann sollte man gleich alle Extensions aktualisieren. In der Erweiterungsverwaltung geht das sehr bequem per Knopfdruck.

Verwaiste Files eliminieren

Manchmal führen auch Skripts, die zwar einmal zum Contao Core gehört haben, in der neuen Version aber nicht mehr existieren, zu seltsamen Fehlern. Solche verwaisten Dateien zu eliminieren hat bei mir schon mehrfach geholfen, wenn sonst nichts mehr ging. Für gewisse Versionen findet man entsprechende Listen (z.B. verwaiste Contao 2.11.6-Dateien in Contao 3), man kann aber auch den Synchronisations-Modus eines geeigneten FTP Clients benutzen (Anleitung).

Cache leeren

Auch der Cache (der Contao Cache – nicht der Browser Cache) kann die Ursache für Probleme beim Upgrade sein. Der extremste Fall war die Fehlermeldung Fatal error: Class ‘BackendInstall’ not found in /var/www/contao/install.php on line 25 beim Aufruf des Installers. Die Lösung bestand darin, den Cache zu leeren, d.h. mit einem FTP Client alle Dateien und Verzeichnisse innerhalb von system/cache/ zu löschen.

Dateiendung von Templates anpassen

Wenn Sie eine sehr alte Contao-Installation upgraden, dann haben Ihre Templates allenfalls noch die Dateiendung *.tpl, was zu der folgenden Fehlermeldung führt: Notice: Using .tpl files (templates/xxxxxxx.tpl) is deprecated. Please use the new .html5 and .xhtml files instead. Seit Contao 2.10 muss die Dateiendung *.xhtml (HTML4) bzw. *.html5 (HTML5) lauten; benennen Sie also die Template-Dateien entsprechend um.

Umstellung von mysql auf mysqli

Contao: Auswahl des Datenbank-Treibers

Ebenfalls beim Upgrade einer sehr alten Contao-Installation erhielt ich im Installer die Warnung, dass mysql veraltet (deprecated) ist und stattdessen die Nutzung von mysqli empfohlen wird. Diese Warnung klingt dramatischer, als sie ist: Man muss nicht etwa eine neue Datenbank installieren, sondern lediglich eine Konfigurationseinstellung im Installer anpassen: Es geht darum, welche Erweiterung PHP für Zugriffe auf die Datenbank nutzt. Im Contao Installer ist die entsprechende Einstellung unter Datenbankverbindung > Treiber zu finden.

Einstellungen auffrischen

Nach meiner Beobachtung vergisst Contao beim Upgrade gelegentlich, dass eine bestimmte Checkbox ursprünglich selektiert war. So sind beispielsweise Kopf- und Fussbereiche in einem Layout nicht mehr aktiv, oder die Stylesheets sind nicht mehr eingebunden, oder eine Seite hat kein Layout mehr zugeordnet. Das kann im Frontend mehr oder weniger dramatische Auswirkungen haben, ist allerdings schnell behoben, wenn man herausgefunden hat, welche Checkbox man nochmals neu anklicken muss. Ähnlich kann es auch passieren, dass beispielsweise bei Datei-Downloads die Referenz auf ein PDF-Dokument in der Dateiverwaltung verlorengegangen ist – das Dokument selbst ist aber noch vorhanden und muss nur neu verlinkt werden.

Stylesheets anpassen

Schliesslich kommt es nach einem Upgrade typischerweise zu einzelnen Darstellungsfehlern, weil Contao gewisse Inhalte leicht anders rendert als früher. Gewisse Anpassungen sind auf HTML5 zurückzuführen, andere auf die Vereinheitlichung und Optimierung der Templates und Module. Oft braucht es nicht viel, dass eine Contao-Website durch ein Upgrade übel zugerichtet wird: Ein neues HTML-Tag oder ein veränderter Klassenbezeichner reicht aus, dass eine Style-Definition nicht mehr greift. Hier muss man mit den üblichen Debugging-Techniken eines Web Developers dahinter, um die Ursache zu finden und die Stylesheets entsprechend anzupassen.

System-Log überprüfen

Selbst wenn scheinbar alles in Ordnung ist: Werfen Sie bei einem Contao-Upgrade unbedingt auch einen Blick in das System-Log. Filtern Sie das Log nach der Kategorie ERROR, um Hinweise auf mögliche Probleme zu erhalten.

Ein Gedanke zu „Contao CMS upgraden: Typische Probleme – und wie man sie löst“

Hinterlassen Sie einen Kommentar