Sulu 2.x Upgrade Guide: So gelingt euer Update ohne Downtime und Kopfschmerzen

Ihr nutzt das Sulu CMS für eure Projekte und wollt auf die neueste Version upgraden? Perfekt! Nach über 20 erfolgreichen Sulu-Upgrades bei unseren Kunden haben wir die häufigsten Stolpersteine identifiziert und zeigen euch, wie ihr sie vermeidet.

Die goldene Regel: Klein anfangen, groß rauskommen

Sulu empfiehlt explizit, große Upgrades zu vermeiden, die Sulu, PHP und Symfony gleichzeitig anpacken. Stattdessen solltet ihr schrittweise vorgehen. Warum? Ganz einfach: Bei Problemen wisst ihr sofort, wo der Fehler liegt.

Der bewährte Upgrade-Prozess in 4 Schritten

Schritt 1: Sulu-Package aktualisieren

Ihr könnt direkt das sulu/sulu Package auf die gewünschte Version updaten:

composer require sulu/sulu:"~2.6.0" --no-update
composer update

Das --no-update Flag verhindert zunächst die automatische Installation aller Dependencies und gibt euch mehr Kontrolle über den Prozess.

Schritt 2: Skeleton-Änderungen prüfen

Das sulu/skeleton Repository enthält die Projektvorlage für Sulu-Projekte und wird zwischen Versionen angepasst, um neue Features zu unterstützen. Schaut euch die Änderungen zwischen eurer aktuellen und der Zielversion an:

# Beispiel für Upgrade von 2.4 auf 2.6
git diff v2.4.0..v2.6.0 -- config/

Schritt 3: UPGRADE.md checken

Die UPGRADE.md Datei im sulu/sulu Repository enthält alle Breaking Changes zwischen verschiedenen Versionen. Das ist euer Rettungsanker, falls etwas schiefgeht. Die meisten Projekte sind nicht betroffen, aber besser safe than sorry.

Schritt 4: Admin-Build aktualisieren

Der häufigste Fehler beim Sulu-Upgrade: Das vergessene Admin-Build-Update! Sulu stellt dafür einen praktischen Befehl bereit:

bin/console sulu:admin:update-build

Die 10 häufigsten Upgrade-Probleme und ihre Lösungen

1. „PDOException: Table doesn’t exist“ nach dem Upgrade

Problem: Die Datenbank-Struktur wurde nicht korrekt migriert.

Lösung: Führt die Migrations manuell aus:

bin/console doctrine:migrations:migrate
bin/console sulu:build prod

2. Admin-Interface zeigt weißen Bildschirm

Problem: JavaScript-Build ist veraltet oder fehlerhaft.

Lösung: Build neu erstellen:

rm -rf public/build/admin
bin/console sulu:admin:update-build

3. „Class not found“ Errors nach dem Update

Problem: Autoloader-Cache ist veraltet.

Lösung: Caches komplett leeren:

rm -rf var/cache/*
composer dump-autoload

4. Composer kann Versionskonflikt nicht auflösen

Problem: Abhängigkeiten sind inkompatibel.

Lösung: Schrittweise Update-Strategie anwenden:

composer why-not sulu/sulu:^2.6
composer update --with-dependencies sulu/sulu

5. „Memory limit exceeded“ während des Updates

Problem: Composer braucht mehr Arbeitsspeicher.

Lösung: Memory Limit temporär erhöhen:

php -d memory_limit=2G /usr/local/bin/composer update

6. Admin-Build schlägt mit Node.js Fehlern fehl

Problem: Node.js oder npm Version ist inkompatibel mit den Sulu-Requirements.

Lösung: Node Version prüfen und ggf. aktualisieren:

node --version  # Sollte >= 14.x sein
npm --version   # Sollte >= 6.x sein
npm install

7. Webspace-Konfiguration funktioniert nicht mehr

Problem: Template-Struktur hat sich geändert.

Lösung: Webspace-Config gegen Skeleton vergleichen:

diff config/webspaces/example.xml vendor/sulu/skeleton/config/webspaces/example.xml

8. Performance-Probleme nach dem Upgrade

Problem: Neue Symfony-Version benötigt andere Cache-Einstellungen.

Lösung: OPcache und Symfony-Cache optimieren:

bin/console cache:clear --env=prod
bin/console cache:warmup --env=prod

9. „Permission denied“ bei Admin-Build

Problem: Dateiberechtigungen sind falsch gesetzt.

Lösung: Berechtigungen korrigieren:

sudo chown -R www-data:www-data public/build
chmod -R 755 public/build

10. Upgrade bricht mit Timeout ab

Problem: Upgrade-Prozess dauert zu lange.

Lösung: Timeout-Limits erhöhen:

php -d max_execution_time=300 -d memory_limit=2G composer update

Never Code Alone Upgrade-Checkliste

Damit ihr nichts vergesst, haben wir eine Checkliste für euch:

• [ ] Backup der aktuellen Installation erstellen
• [ ] Testumgebung aufsetzen
• [ ] PHP/Symfony-Kompatibilität prüfen
• [ ] composer.json Version anpassen
• [ ] composer update ausführen
• [ ] Skeleton-Änderungen reviewen und übernehmen
• [ ] UPGRADE.md durchlesen
• [ ] Admin-Build aktualisieren
• [ ] Funktionalität testen
• [ ] Performance prüfen
• [ ] Live-Deployment

Unser Tipp: Upgrade-Strategie für Teams

Bei Never Code Alone handhaben wir Sulu-Upgrades immer im Team. Warum? Weil vier Augen mehr sehen als zwei:

1. Developer 1: Führt das technische Upgrade durch
2. Developer 2: Testet kritische User Journeys
3. QA: Prüft Admin-Interface und Content-Erstellung
4. DevOps: Monitort Performance und Logs

Braucht ihr Unterstützung?

Sulu-Upgrades können tricky sein, besonders bei größeren Projekten mit Custom-Bundles. Falls ihr bei eurem Upgrade Unterstützung braucht oder einfach sichergehen wollt, dass alles glatt läuft – meldet euch bei uns!

Roland Golla ist Sulu-Experte und hat bereits über 50 CMS-Projekte erfolgreich migriert. Mit Never Code Alone könnt ihr sicher sein, dass euer Upgrade professionell und ohne Ausfallzeiten durchgeführt wird.

Einfach eine Mail an roland@nevercodealone.de – wir helfen gerne weiter!

---

*Never Code Alone – Initiative für Software-Qualität in Deutschland. Folgt uns für mehr Tipps zu Web Development, Testing und allem