Lernseite · Installation, Composer und Upgrades
TYPO3 installieren, mit Composer pflegen und sicher aktualisieren
Bevor die Website der Musikschule Lindenau Inhalte bekommt, braucht sie eine saubere Installation. Diese Seite begleitet die Integratorin Mara vom ersten Composer-Befehl bis zum Upgrade auf die nächste Hauptversion. Danach kennst du die Verzeichnisse eines Composer-Projekts, den Unterschied zwischen install und update, die composer.json einer Extension, den Ablauf eines Major-Upgrades und die wichtigsten Werkzeuge für System Maintainer.
Installation mit Composer und DDEV
Mara baut die Website der Musikschule Lindenau. Ihr Sitepackage hat den Extension-Key lindenau_site und heißt als Composer-Paket lindenau/site. Das ganze Projekt verwaltet sie mit Composer.
Composer ist der Paketmanager für PHP. In der Datei composer.json steht, welche Pakete ein Projekt braucht. Composer lädt diese Pakete samt ihren Abhängigkeiten in den Ordner vendor/. Andere Paketmanager haben andere Aufgaben: npm ist für JavaScript da, pip für Python und apt-get für Systempakete eines Linux-Servers. Die empfohlene Installation von TYPO3 läuft über Composer.
Auf ihrem Rechner arbeitet Mara mit DDEV. DDEV startet Container mit Webserver, PHP und Datenbank, die zu TYPO3 passen. Die TYPO3-Dokumentation empfiehlt es für die lokale Entwicklung. Ein FTP-Programm wie FileZilla oder ein API-Werkzeug wie Postman ersetzt das nicht. Für TYPO3 14 braucht der Server PHP ab Version 8.2 und Composer ab Version 2.1.
Das neue Projekt entsteht aus dem Paket Base Distribution. Es bringt eine passende composer.json und die wichtigsten System-Extensions mit. Danach richtet der Befehl setup die Installation ein. Er fragt den Datenbankzugang, das erste Admin-Konto und die Einstellungen der ersten Site ab und schreibt die Konfiguration.
composer create-project "typo3/cms-base-distribution:^14.3" lindenau
vendor/bin/typo3 setupDanach meldet sich Mara im Backend an, legt die ersten Seiten an und trägt Einstellungen der Site ein. Erscheint eine Änderung an TypoScript, Templates oder Site-Einstellungen nicht im Frontend, liegt das meist am Cache. Dann leert sie die Caches, im Backend über das Blitz-Symbol oder auf der Kommandozeile mit dem Befehl cache:flush.
Die Verzeichnisse eines Composer-Projekts
Ein Composer-Projekt trennt streng, was öffentlich sein darf und was privat bleiben muss. Das ist eine Sicherheitsfrage.
- Der Ordner
config/hält die Konfiguration. Im Unterordnerconfig/system/liegensettings.php, die TYPO3 über das Backend schreibt, undadditional.php, die du von Hand pflegst. Im Unterordnerconfig/sites/liegt je Site ein Ordner mit der Site-Konfiguration. - Der Ordner
public/enthält alles, was öffentlich erreichbar sein soll. Auf ihn muss das Document Root des Webservers zeigen. Hier liegen die zentraleindex.php,fileadmin/und_assets/. - Der Ordner
var/enthält private, temporäre Dateien. Dazu gehörenvar/cache/für Caches,var/log/für Logs undvar/labels/für heruntergeladene Übersetzungen. - Der Ordner
vendor/gehört Composer. Dort installiert Composer alle Pakete, zum Beispiel den Core untervendor/typo3/cms-coreund die News-Extension untervendor/georgringer/news. - Der Ordner
packages/ist für eigene Extensions und das Sitepackage gedacht. Die Base Distribution trägt ihn in dercomposer.jsonals Repository vom Typ path ein.
Was nicht hineingehört: In vendor/ legst du nie eigene Dateien von Hand ab. Der nächste Composer-Lauf oder das nächste Deployment überschreibt sie. Mara legt ihr Sitepackage deshalb in packages/ und installiert es mit composer require. Composer verlinkt es dann nach vendor/.
fileadmin gehört der Redaktion. Hier liegen Bilder, PDFs und Videos, die Redakteure hochladen. Es ist nur der Standardspeicher. Über das File Abstraction Layer, kurz FAL, lassen sich weitere Speicher einbinden. Logo, CSS und Templates gehören nicht nach fileadmin/, etwa in einen Ordner layout. Die Redaktion könnte sie ändern oder löschen, und sie wären nicht versioniert. Diese Dateien liefert Mara im Sitepackage aus, im Ordner Resources/Public.
var nie ganz löschen. Wer den ganzen Ordner var/ entfernt, riskiert Fehler im Betrieb oder beim Deployment. Leere nur gezielt einzelne Unterordner. Fehlende Ordner und falsche Rechte findet ein System Maintainer im Backend unter System, Environment, Directory Status. Dort lassen sich fehlende Ordner auch anlegen.
Seit TYPO3 14 fehlt public/typo3. Die Dateien index.php und install.php im Ordner public/typo3/ gibt es nicht mehr. Backend und Install Tool laufen über die zentrale index.php im Webroot. Das Install Tool erreichst du unter dem Pfad typo3, Schrägstrich, install. Die alte Adresse mit install.php beantwortet TYPO3 weiter als Route. Ein Monitoring, das noch die alte Datei index.php im Ordner typo3 aufruft, bekommt nach dem Upgrade einen Fehler.
Öffentliche Dateien der Extensions
Extensions bringen CSS, JavaScript, Schriften und Bilder mit. Im Composer-Modus liegen sie unter vendor/, also außerhalb des Webroots. Damit der Browser sie trotzdem laden kann, veröffentlicht TYPO3 nur den Ordner Resources/Public jeder Extension unter public/_assets/. Meist geschieht das per Symlink, also über einen Verweis. Templates und PHP-Dateien der Extension bleiben so privat. Den Ordner _assets/ bearbeitest du nie von Hand.
Seit TYPO3 14.2 veröffentlicht der Befehl asset:publish die öffentlichen Ressourcen. Er läuft bei composer install automatisch mit, ebenso beim Befehl extension:setup. Mit der Umgebungsvariablen TYPO3_SKIP_ASSET_PUBLISH überspringst du nur diesen Schritt während composer install.
Kopieren statt verlinken: Manche Server erlauben keine Symlinks oder haben ein schreibgeschütztes Dateisystem. Dafür gibt es seit 14.2 die Option filesystemPublishingType im Bereich SYS/SystemResources der Systemkonfiguration. Sie kennt drei Werte:
- Der Standard link legt Verweise an.
- Der Wert mirror kopiert die Dateien nach
_assets/. - Der Wert auto kopiert im Kontext Production und verlinkt im Kontext Development.
Nie von live nach lokal kopieren. In der Entwicklung müssen unter _assets/ Verweise liegen. Kopiert Mara den Ordner vom Live-Server zurück, zeigen die Dateien nach dem nächsten Composer-Update nicht auf die neuen JavaScript- und CSS-Dateien. Dann läuft alter Code im Browser mit neuem Code auf dem Server, und Backend und Frontend zeigen Fehler. Synchronisiert wird nur in eine Richtung: von der Entwicklung nach live.
Composer im Alltag
Zwei Dateien sind entscheidend. In der composer.json stehen unter require die Pakete mit ihren Versionsvorgaben. Die composer.lock hält fest, welche Version jedes Pakets genau installiert ist. Composer schreibt sie selbst. Du bearbeitest sie nie von Hand.
Für TYPO3 trägt Mara die Vorgabe ^14.3 ein. Das Dach-Zeichen, Caret genannt, erlaubt alle Versionen ab 14.3.0 und unter 15.0.0. Nach Semantic Versioning sind das kompatible Updates. Für den Sprung auf TYPO3 15 muss sie die Vorgabe selbst ändern.
Die wichtigsten Befehle:
- Der Befehl
composer create-projectlegt ein neues Projekt aus einem Paket an. - Der Befehl
composer requirefügt ein Paket hinzu, zum Beispiel die Extensiongeorgringer/news. Er trägt es in diecomposer.jsonein, installiert es und aktualisiert diecomposer.lock. - Der Befehl
composer removeentfernt ein Paket aus dercomposer.jsonund ausvendor/und aktualisiert diecomposer.lock. - Der Befehl
composer installinstalliert genau die Versionen aus dercomposer.lock. - Der Befehl
composer updatelöst die Vorgaben dercomposer.jsonneu auf, installiert passende neuere Versionen und schreibt diecomposer.lockneu.
Befehle wie add, get, fetch, uninstall, delete oder drop kennt Composer nicht. Fehlt die composer.lock, verhält sich composer install wie ein Update: Es löst die Vorgaben selbst auf und schreibt eine neue Lock-Datei.
Mara checkt die composer.lock ins Versionskontrollsystem ein. So installiert composer install lokal, auf Staging und live dieselben Versionen. Zugangsdaten stehen in dieser Datei nicht.
Achtung bei Caches: Der Befehl composer clear-cache leert nur den Download-Cache von Composer. Die Caches von TYPO3 erreicht er nicht.
Das Sitepackage als Composer-Paket
Jede Extension braucht eine eigene composer.json. Mara schreibt sie für das Sitepackage so:
{
"name": "lindenau/site",
"type": "typo3-cms-extension",
"description": "Lindenau Site - Sitepackage der Musikschule Lindenau",
"require": {
"typo3/cms-core": "^14.3"
},
"autoload": {
"psr-4": { "Lindenau\\Site\\": "Classes/" }
},
"extra": {
"typo3/cms": { "extension-key": "lindenau_site" }
}
}- Das Feld type hat den Wert
typo3-cms-extension. Daran erkennt der Composer-Installer von TYPO3 das Paket als Extension. Der Typ library steht für normale PHP-Bibliotheken, project für ein ganzes Projekt. - Unter extra, Schlüssel
typo3/cms, steht der Extension-Key. - Unter require steht die Abhängigkeit zum Core.
- Zugangsdaten zur Datenbank gehören nie in eine
composer.json.
Der Titel kommt seit TYPO3 14 aus der Beschreibung. So muss TYPO3 im Composer-Modus die alte ext_emconf.php dafür nicht mehr lesen. Steht im Feld description die Zeichenfolge Leerzeichen, Bindestrich, Leerzeichen, wird alles davor zum Titel und der Rest zur Beschreibung. Es zählt nur das erste Vorkommen. Fehlt die Zeichenfolge, erscheint die ganze Beschreibung als Titel.
Auch der Classic-Modus braucht seit TYPO3 14 eine composer.json. Eine ältere Extension, die nur eine ext_emconf.php hat, wird nicht mehr erkannt. Ihre composer.json braucht einen type, der mit typo3-cms beginnt, und den Extension-Key unter extra.
Autoloading im Classic-Modus: Ohne Composer erzeugt TYPO3 die Autoload-Daten selbst. Bekommt eine Extension neue Klassen, setzt die Karte Rebuild PHP Autoload Information im Modul Maintenance diese Daten neu. Der Befehl composer dump-autoload setzt dagegen eine Composer-Installation voraus.
Composer oder Classic? Der Vorteil von Composer: Abhängigkeiten werden aufgelöst, und die Versionen sind festgeschrieben und reproduzierbar. Der Nachteil: Man braucht Composer, das nötige Wissen und meist einen Zugang zur Kommandozeile. Extensions direkt aus dem TYPO3 Extension Repository, kurz TER, im Extension Manager laden geht nur im Classic-Modus. Sicherheitsupdates bekommen beide Varianten.
Ein Major-Upgrade vorbereiten
Ein Major-Upgrade ist der Sprung auf eine neue Hauptversion, zum Beispiel von TYPO3 13 auf 14. Es hat drei Phasen: Vorbereitung, das Core-Update selbst und die Nacharbeiten.
Vorher erledigt Mara vier Dinge:
- Sie legt ein vollständiges Backup von Datenbank und Dateien an. Der Merksatz dazu lautet: No backup, no sympathy.
- Sie wertet das Deprecation-Log aus und behebt alle Deprecations der aktuellen Version.
- Sie prüft jede Extension auf eine Version für die Zielversion, im TER und auf packagist.org.
- Sie führt alle Upgrade Wizards der aktuellen Version aus.
Was sich im Core geändert hat, steht in den Changelogs von TYPO3. Im Modul Upgrade zeigt sie die Karte View Upgrade Documentation. Für Extensions hilft das Modul Upgrade im Bereich System mit vier Prüfungen.
- Die Karte Scan Extension Files durchsucht den PHP-Code der Extensions nach Aufrufen, die laut Changelog veraltet oder entfernt sind.
- Die Karte Check for Broken Extensions prüft, ob die aktiven Extensions lauffähig sind.
- Die Karte Check TCA Migrations findet veraltete Einstellungen im TCA von Extensions.
- Die Karte Check TCA in ext_tables.php findet Extensions, die das TCA in dieser Datei ändern.
Das Core-Update selbst läuft im Composer-Modus über Composer. Mara hebt in der composer.json die Vorgaben der Core-Pakete an, etwa auf ^14.3, und führt composer update aus. Die Karte Update TYPO3 Core im Modul Upgrade funktioniert nur im Classic-Modus. Dort aktualisiert sie auf Knopfdruck innerhalb einer Hauptversion, für Fehlerbehebungen und Sicherheitsupdates. Die Datei settings.php zu ersetzen oder den Core im Extension Manager neu zu installieren ist dagegen kein Weg.
Mara probt das Upgrade zuerst auf einer Kopie der Live-Seite. Erst wenn dort alles läuft, ist die echte Website dran.
Nach dem Core-Update
Direkt nach dem Core-Update folgen die Nacharbeiten in einer festen Reihenfolge. Die Werkzeuge dafür liegen in den Modulen Maintenance und Upgrade.
- Im Modul Maintenance mit Flush TYPO3 and PHP Cache alle Caches leeren.
- Mit Analyze Database Structure, dem Database Analyzer, fehlende Tabellen und Spalten anlegen.
- Alle Upgrade Wizards ausführen.
- Im Database Analyzer veraltete Spalten und Tabellen ändern oder entfernen.
- Die Caches erneut leeren.
- Optional die Einstellungen der Backend-Benutzer zurücksetzen.
- Die Sprachpakete aktualisieren.
- Die Webserver-Konfiguration prüfen, etwa die htaccess mit der neuen Vorlage vergleichen.
Warum erst nach den Wizards entfernen? Viele Wizards kopieren Daten aus alten Feldern in neue. Löscht Mara die alten Spalten vorher, sind diese Daten verloren. Deshalb kommen „change“ und „remove“ im Database Analyzer erst nach den Wizards. Seitenbaum und Extensions bleiben bei all dem unangetastet.
Zu den Nacharbeiten gehört auch eigener Code. Mara passt im Sitepackage Stellen an, die entfernte oder geänderte Schnittstellen nutzen, und aktualisiert Extensions auf die passenden Versionen.
Upgrade Wizards
Upgrade Wizards prüfen nach einem Update von Core oder Extension, ob Daten oder Konfiguration angepasst werden müssen. Wenn ja, führen sie diese Migration aus. Sie legen keine Backups an, laden keine neuen Versionen herunter und gestalten nichts im Frontend um.
Voraussetzung: Wizards arbeiten mit der neuen Datenbankstruktur. Fehlen Tabellen oder Spalten, legt Mara sie zuerst im Database Analyzer an. Die Wizards ersetzen den Database Analyzer also nicht.
Wo: Im Backend liegen sie im Modul Upgrade, Karte Upgrade Wizard. Das Modul sehen nur System Maintainer. Es stammt, wie die Module Maintenance, Settings und Environment, aus dem Paket typo3/cms-install. Seit TYPO3 14 ist dieses Paket in minimalen Composer-Installationen nicht mehr standardmäßig dabei. Fehlt das Modul Upgrade, obwohl Mara System Maintainerin ist, fehlt meist dieses Paket.
Auf der Kommandozeile gehen die Wizards auch ohne dieses Paket, denn die Befehle liegen seit TYPO3 14 im Core:
vendor/bin/typo3 upgrade:list
vendor/bin/typo3 upgrade:run
vendor/bin/typo3 upgrade:run <kennung>
vendor/bin/typo3 upgrade:mark:undone <kennung>Im Backend setzt du einen erledigten Wizard in der Liste der erledigten Wizards zurück.
Weitere Regeln:
- Manche Wizards sind optional, zum Beispiel einer, der eine Extension installiert. Sie lassen sich überspringen.
- Auch Extensions bringen eigene Wizards mit.
- Wizards gibt es nicht nur bei Major-Upgrades. Sieh nach jedem Major- oder Minor-Update des Core nach offenen Wizards, also auch nach dem Schritt von 14.2 auf 14.3. Dasselbe gilt nach Updates von Extensions mit eigenen Wizards.
- Wizards laufen nie automatisch im Frontend.
- Vor dem Sprung auf die nächste Hauptversion müssen alle Wizards der aktuellen Version erledigt sein.
Der Bereich für System Maintainer
Unter System im Backend liegen die Module Maintenance, Settings, Upgrade und Environment. Sie sind nur für Backend-Benutzer zugänglich, die Admin und System Maintainer sind. Funktioniert das Backend nicht, ist das Install Tool direkt über die URL erreichbar, nachdem man auf dem Server die Datei ENABLE_INSTALL_TOOL angelegt hat. So sperrst und entsperrst du das Install Tool.
Das Modul Maintenance hat diese wichtigen Karten.
- Die Karte Flush TYPO3 and PHP Cache leert alle registrierten TYPO3-Caches und zusätzlich den Opcode-Cache von PHP und den Cache der Dependency Injection. Das braucht man etwa nach Major-Upgrades. Browser-Caches der Besucher, ein vorgeschaltetes CDN oder den Download-Cache von Composer erreicht sie nicht.
- Die Karte Analyze Database Structure vergleicht die Datenbank mit den Definitionen der aktiven Extensions und legt fehlende Tabellen und Felder an.
- Die Karte Clear Persistent Database Tables leert dauerhafte Tabellen, die nichts mit Caches zu tun haben. Dazu gehören die Sitzungstabellen be_sessions und fe_sessions, das Protokoll sys_log, die CSP-Berichte in sys_http_report und mit Workspaces die Vorschau-Links in sys_preview. Wer die Sitzungen leert, meldet alle Benutzer ab. Seiten und Inhalte bleiben erhalten.
- Die Karte Create Administrative User legt neue Admins an, auf Wunsch gleich als System Maintainer.
- Die Karte Manage Language Packs lädt und aktualisiert die Sprachpakete.
- Die Karte Rebuild PHP Autoload Information funktioniert nur im Classic-Modus. Im Composer-Modus ist sie ausgegraut und verweist auf Composer.
Das Modul Environment prüft die Umgebung. Die Karte Directory Status kontrolliert Ordnerstruktur und Dateirechte. Die Karte Test Mail Setup schickt eine Testmail.
Vieles geht auch auf der Kommandozeile. In TYPO3 14 gibt es dafür diese Befehle:
- Der Befehl
cache:flushleert alle Caches. Mit der Option group und dem Wert system oder pages leert er nur eine Gruppe. - Der Befehl
backend:user:createlegt Backend-Benutzer an, auch Admins. - Der Befehl
language:updateaktualisiert die Sprachpakete. - Der Befehl
upgrade:runführt Upgrade Wizards aus. - Der Befehl
install:password:setsetzt das Passwort des Install Tools. - Der Befehl
extension:setuprichtet Extensions ein und legt dabei auch ihre Tabellen an.
Einen Core-Befehl database:compare oder ter:download gibt es dagegen nicht. Erfundene Varianten wie cache:delete, flush:all oder backend:user:add auch nicht.
Log-Dateien rotieren
TYPO3 schreibt seine Logs im Composer-Modus nach var/log/, außerhalb des Webroots. So sind sie im Browser nicht abrufbar. Dort liegen das allgemeine Log, dessen Dateiname mit typo3 und einem Kürzel beginnt, das Deprecation-Log und Logs von Extensions. Ohne Pflege wachsen diese Dateien unbegrenzt.
Auf großen Servern übernimmt das ein Werkzeug wie logrotate. Die Musikschule hat aber ein Shared Hosting ohne Root-Zugriff. Dafür bringt TYPO3 den RotatingFileWriter mit. Er erweitert den normalen FileWriter. Im eingestellten Rhythmus kopiert er die aktuelle Datei weg, hängt einen Zeitstempel an den Namen und leert die aktuelle Datei.
Zwei Optionen steuern ihn:
- Die Option interval bestimmt den Rhythmus: daily, weekly, monthly oder yearly. Der Standard ist daily.
- Die Option maxFiles bestimmt, wie viele alte Dateien erhalten bleiben. Der Standard ist 5. Der Wert 0 heißt: nie löschen.
Den Namen der Log-Datei passt du mit den Optionen des FileWriter an, etwa mit logFile für einen eigenen Pfad oder mit logFileInfix für einen Namensteil.
$GLOBALS['TYPO3_CONF_VARS']['LOG']['writerConfiguration'] = [
\Psr\Log\LogLevel::ERROR => [
\TYPO3\CMS\Core\Log\Writer\RotatingFileWriter::class => [
'logFileInfix' => 'lindenau',
'interval' => 'weekly',
'maxFiles' => 4,
],
],
];Mit diesen Werten rotiert TYPO3 einmal pro Woche, und höchstens vier alte Dateien bleiben liegen. Es wird nicht geteilt, wenn eine Größe erreicht ist, und es werden auch nicht mehrere Dateien parallel beschrieben.
Das Wichtigste in Kürze
- TYPO3 installierst du mit Composer aus der Base Distribution und richtest es mit dem Befehl setup ein. Lokal hilft DDEV.
- Das Document Root zeigt auf
public/. Die Ordner config, var, vendor und packages liegen außerhalb. fileadmin/gehört der Redaktion, Layout-Dateien gehören ins Sitepackage.- Unter
_assets/liegen nur die OrdnerResources/Publicder Extensions. Fehlt einer, hilftasset:publish. Synchronisiert wird nie von live nach lokal. composer installinstalliert die Versionen dercomposer.lock.composer updatelöst neu auf und gehört nicht auf den Live-Server.- Eine Extension braucht in der
composer.jsonden Typtypo3-cms-extensionund den Extension-Key unter extra. Seit TYPO3 14 gilt das auch im Classic-Modus. - Vor dem Major-Upgrade: Backup, Deprecations beheben, Extensions prüfen, Wizards der aktuellen Version ausführen.
- Danach: Caches leeren, Tabellen anlegen, Wizards ausführen, erst dann Altes entfernen.
- Upgrade Wizards gehören nach jedes Major- und Minor-Update und nach Extension-Updates.
- Der RotatingFileWriter rotiert Logs ohne logrotate, gesteuert über interval und maxFiles.
Begriffe
- Base Distribution
- Composer-Paket typo3 cms-base-distribution, aus dem ein neues TYPO3-Projekt entsteht.
- Caret
- Versionsvorgabe mit Dach-Zeichen, die Updates bis unter die nächste Hauptversion erlaubt.
- Classic-Modus
- Installation ohne Composer, bei der TYPO3 die Pakete und das Autoloading selbst verwaltet.
- composer.lock
- Datei mit den genau installierten Versionen aller Pakete.
- Database Analyzer
- Werkzeug im Modul Maintenance, das die Datenbankstruktur vergleicht und anpasst.
- Document Root
- Ordner, auf den der Webserver zeigt, im Composer-Modus public.
- Major-Upgrade
- Wechsel auf eine neue Hauptversion von TYPO3.
- RotatingFileWriter
- Log-Writer, der Log-Dateien selbst rotiert und alte Dateien aufräumt.
- System Maintainer
- Admin, der die Module Maintenance, Settings, Upgrade und Environment nutzen darf.
- Upgrade Wizard
- Migration, die nach einem Update Daten und Konfiguration anpasst.