Lernseite · Systemkonfiguration und Caching
TYPO3 einstellen, warten und schnell machen
Eine TYPO3-Installation hat Einstellungen, die für alle Seiten gelten: Datenbank, Sitzungen, Bildbearbeitung, Fehlerausgabe. Du lernst, wo sie liegen, wer sie ändern darf und wie du je Umgebung andere Werte setzt. Danach geht es um den Cache und zum Schluss um das Admin Panel, mit dem du langsame Seiten untersuchst.
Das Beispiel: die Musikschule Lindenau
Die Integratorin Mara baut die Website der Musikschule Lindenau als Composer-Projekt mit TYPO3 14.3. Es gibt drei Umgebungen:
- Auf Maras Laptop läuft das Projekt in DDEV unter der Adresse lindenau.ddev.site.
- Ein Testserver zeigt der Schulleitung neue Funktionen, bevor sie live gehen.
- Das Live-System läuft unter www.musikschule-lindenau.example.
Auf dem Laptop will Mara jeden Fehler mit allen Details sehen. Live sollen Besucher nie interne Informationen sehen. Die Startseite soll schnell laden und neue Konzerttermine trotzdem sofort zeigen.
Wo TYPO3 seine Einstellungen speichert
Alle installationsweiten Einstellungen landen im globalen Array TYPO3_CONF_VARS. Es ist in Bereiche gegliedert: BE für das Backend, FE für das Frontend und SYS für allgemeine Systemwerte. Dazu kommen DB für die Datenbank, GFX für Bilder und MAIL für den Mailversand. Verwechsle es nicht mit dem Array TCA, das Tabellen und Felder beschreibt.
Gefüllt wird das Array in drei Schichten:
- Die Standardwerte stehen in
DefaultConfiguration.phpin der Core-Extension. Diese Datei änderst du nie. - Die Datei
settings.phpim Ordnerconfig/systementhält alles, was von den Standardwerten abweicht. - Die Datei
additional.phpim selben Ordner wird danach geladen und kann jeden Wert überschreiben.
Die settings.php ist eine maschinell geschriebene Datei. TYPO3 schreibt sie jedes Mal neu, wenn ein System Maintainer im Modul Settings unter System etwas speichert. Auch das Install-Tool-Passwort steht dort, als Hash unter dem Schlüssel installToolPassword im Bereich BE. Du darfst die Datei von Hand bearbeiten. Beim nächsten Speichern im Backend erzeugt TYPO3 sie aber komplett neu, und deine Kommentare sind weg. Composer hat mit dieser Datei nichts zu tun.
Die additional.php pflegst du selbst. TYPO3 überschreibt sie nie. Sie ist eine normale PHP-Datei und darf Logik enthalten, etwa eine Abfrage des Application Context. Sie wird bei jeder Anfrage geladen, also gehört dort keine aufwendige Rechenarbeit hinein. Ein Wert aus der additional.php gewinnt immer, auch wenn das Backend einen anderen Wert anzeigt.
<?php
use TYPO3\CMS\Core\Core\Environment;
if (Environment::getContext()->isDevelopment()) {
$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['host'] = 'db';
$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['password'] = 'db';
} else {
$GLOBALS['TYPO3_CONF_VARS']['BE']['lockSSL'] = true;
}Andere Konfiguration liegt woanders: Die Site-Konfiguration steht in YAML-Dateien unter config/sites, und die Datei .htaccess steuert den Webserver. Seit TYPO3 14.2 kannst du einzelne Werte der settings.php auch auf der Kommandozeile lesen und setzen, mit configuration:show und configuration:set aus der Systemerweiterung lowlevel.
Der Application Context
Der Application Context sagt TYPO3, in welcher Umgebung es läuft. Es gibt drei Hauptkontexte: Production, Development und Testing. Dazu kommen Unterkontexte, zum Beispiel Production/Staging für Maras Testserver. Ist nichts gesetzt, gilt Production.
Den Kontext setzt du über die Umgebungsvariable TYPO3_CONTEXT. Bei Apache geht das mit SetEnv im vHost oder in der .htaccess, auch abhängig von der Domain. Variablen wie APP_ENV oder NODE_ENV gehören zu anderen Frameworks und haben für TYPO3 keine Bedeutung.
SetEnv TYPO3_CONTEXT Production/StagingTYPO3_CONTEXT=Development vendor/bin/typo3 cache:flushWelcher Kontext gerade gilt, siehst du im Backend im Menü System Information in der oberen Leiste, neben der TYPO3-Version und der PHP-Version. So erkennst du sofort, ob du live arbeitest.
Auf den Kontext reagieren kannst du an mehreren Stellen:
- In der additional.php mit einer Abfrage, wie im Beispiel oben.
- In TypoScript mit der Bedingung applicationContext. Für Unterkontexte eignet sich der Vergleich mit matches und einem regulären Ausdruck.
- In stdWrap mit getText, also data mit dem Wert applicationcontext.
- In der Site-Konfiguration mit
baseVariants. Dort stehen andere Basis-Adressen mit einer Bedingung. Trifft keine zu, gilt die normale Basis.
[applicationContext == "Development"]
page.10.value = Entwicklungssystem
[end]
[applicationContext matches "/^Production/"]
config.admPanel = 0
[end]
page.20 = TEXT
page.20.data = applicationcontextbase: 'https://www.musikschule-lindenau.example/'
baseVariants:
- base: 'https://lindenau.ddev.site/'
condition: 'applicationContext == "Development"'So braucht Mara nur einen Seitenbaum und eine Site-Konfiguration für alle Umgebungen.
System Maintainer im Backend
Die Wartungswerkzeuge von TYPO3 heißen zusammen System Maintainer Area, früher Install Tool. Im Backend sind das die Module Maintenance, Settings, Upgrade und Environment unter System. Diese Module sehen nur Admins, die zugleich System Maintainer sind. Redakteure ohne Adminrechte sind nie System Maintainer, egal in welcher Gruppe sie stehen.
Wer System Maintainer ist, steht in der Liste systemMaintainers im Bereich SYS, als Liste von Benutzer-IDs. Du pflegst sie im Modul Settings über die Karte Manage System Maintainers. Eine eigene Benutzergruppe dafür gibt es nicht. Bei der Einrichtung trägt TYPO3 den ersten Admin selbst ein.
Wie streng TYPO3 ist, hängt vom Kontext ab:
- Im Kontext Development gilt jeder Admin als System Maintainer, auch wenn die Liste leer ist. Eine zusätzliche Bestätigung entfällt.
- In Production gilt die Liste. Vor dem Öffnen der Module verlangt TYPO3 eine erneute Bestätigung, den sogenannten Sudo-Modus. Du gibst dein Backend-Passwort oder das Install-Tool-Passwort noch einmal ein.
Kennt niemand mehr das Install-Tool-Passwort, kommt ein System Maintainer trotzdem über die Module unter System an alle Wartungsfunktionen. Dort kann er auch ein neues Install-Tool-Passwort vergeben.
Das Install Tool ohne Backend
Das Install Tool gibt es auch als eigenständigen Zugang ohne Backend-Login. Standardmäßig erreichst du es unter dem Pfad /typo3/install. Seit TYPO3 14 hängt es an den Backend-Routen und folgt dem Backend-Einstiegspunkt. Steht entryPoint im Bereich BE auf admin, liegt das Install Tool unter /admin/install.
Weil kein Backend-Konto nötig ist, schützt TYPO3 diesen Zugang doppelt:
- Es muss eine Datei namens ENABLE_INSTALL_TOOL existieren. Wer sie anlegen kann, hat Schreibzugriff auf den Server.
- Du brauchst das Install-Tool-Passwort. Es ist unabhängig von allen Backend-Passwörtern.
Wohin mit der Datei? In einer Composer-Installation wertet TYPO3 zwei Orte aus: den Ordner var/transient und den Ordner config. In einer Classic-Installation ohne Composer sind es typo3temp/var/transient und typo3conf. Im Webroot public oder unter vendor wird die Datei nicht beachtet. Andere Merkerdateien haben andere Aufgaben: FIRST_INSTALL startet die Erstinstallation, LOCK_BACKEND sperrt das Backend.
Die Datei verfällt. Sie gilt 60 Minuten, jede Nutzung des Install Tools verlängert die Frist. Ist sie abgelaufen, löscht TYPO3 sie beim nächsten Zugriff, und das Install Tool ist wieder gesperrt. Auch beim Abmelden verschwindet sie. Steht in der Datei der Text KEEP_FILE, bleibt sie dagegen liegen. Dann musst du sie von Hand löschen, sonst bleibt das Install Tool offen und nur durch das Passwort geschützt. Der Statusbericht warnt davor.
touch var/transient/ENABLE_INSTALL_TOOL
echo KEEP_FILE > var/transient/ENABLE_INSTALL_TOOLDas Passwort legst du bei der Installation fest. Seit TYPO3 14 kannst du es auf der Kommandozeile mit install:password:set setzen oder neu erzeugen lassen. Das klappt nur, wenn die additional.php den Wert nicht überschreibt. Im Install Tool selbst gibt es die Karte Change Install Tool Password im Modul Settings. Verwechsle das nicht mit backend:resetpassword: Dieser Befehl setzt das Passwort eines Backend-Benutzers zurück.
vendor/bin/typo3 install:password:setWenn das Backend kaputt ist, etwa nach einem Fehler in einer Extension, hilft der Parameter __typo3_install an der Startadresse der Website. Er führt zum Installer oder zum Wartungswerkzeug. Die Datei ENABLE_INSTALL_TOOL und das Passwort brauchst du trotzdem.
Installationsweite Optionen und Wartungssperre
Die meisten Systemwerte änderst du im Modul Settings über die Karte Configure Installation-Wide Options. TYPO3 schreibt sie dann in die settings.php. Für Mara sind diese Optionen wichtig:
lockSSLim Bereich BE erzwingt HTTPS für das Backend. Aufrufe ohne HTTPS leitet TYPO3 auf die verschlüsselte Adresse um.cookieDomainim Bereich SYS legt fest, für welche Domain Login-Cookies gelten. Mit dem Wert Punkt musikschule-lindenau.example teilen sich alle Subdomains die Sitzung. Getrennte Werte für Frontend und Backend gibt es mitcookieDomainin den Bereichen FE und BE.sessionTimeoutim Bereich BE beendet eine Backend-Sitzung ohne Aktivität. Standard sind 28800 Sekunden, also 8 Stunden. Für Frontend-Benutzer gilt derselbe Schlüssel im Bereich FE mit 6000 Sekunden.- Im Bereich GFX wählst du das Bildprogramm, also GraphicsMagick oder ImageMagick, und dessen Pfad. Im Bereich MAIL stellst du den Mailversand ein.
Ob die Bildbearbeitung wirklich funktioniert, prüfst du im Modul Environment unter Image Processing. Dort erzeugt TYPO3 Testbilder und stellt sie neben Referenzbilder. Unter Configuration Presets im Modul Settings gibt es außerdem fertige Pakete, etwa Live und Debug für die Fehlerausgabe.
Während einer Wartung willst du verhindern, dass Redakteure gleichzeitig arbeiten. Dafür gibt es adminOnly im Bereich BE:
- Der Wert 0 ist der Normalbetrieb. Alle Benutzer dürfen sich anmelden.
- Der Wert 1 lässt nur Admins und System Maintainer ins Backend. Auch die Kommandozeile ist gesperrt.
- Der Wert 2 lässt ebenfalls nur Admins ins Backend. Befehle auf der Kommandozeile, etwa Scheduler-Aufgaben, laufen aber weiter.
- Der Wert minus 1 schaltet das Backend für alle ab.
Eine zweite Sperre ist die Datei LOCK_BACKEND. Der Befehl backend:lock legt sie an, backend:unlock entfernt sie. Sie sperrt das Backend für alle, auch für Admins. Steht in der Datei eine Adresse, leitet TYPO3 Aufrufe des Backends dorthin um, etwa auf eine Wartungsseite. In Composer-Installationen liegt sie standardmäßig im Ordner var/lock. Soll die Sperre ein Deployment überdauern, müssen sich die Release-Ordner diesen Ordner teilen. Anders als ENABLE_INSTALL_TOOL verfällt LOCK_BACKEND nicht von selbst.
Fehler anzeigen oder verbergen
Wenn PHP einen Fehler meldet oder eine Exception auftritt, entscheidet TYPO3, wie viel davon sichtbar wird. Der Production Exception Handler zeigt nur eine knappe Meldung. Der Debug Exception Handler zeigt Details mit Stacktrace. Die Wahl steuert displayErrors im Bereich SYS:
- Der Wert 1 zeigt Fehler an und nutzt den Debug Exception Handler.
- Der Wert 0 zeigt keine Fehler an und nutzt den Production Exception Handler.
- Der Wert minus 1 ist der Standard. Dann entscheidet die IP-Adresse des Aufrufers.
Beim Wert minus 1 vergleicht TYPO3 die IP-Adresse mit devIPmask im Bereich SYS, der Liste der Adressen, die Debug-Ausgaben sehen dürfen. Standard ist 127.0.0.1 und die IPv6-Adresse für localhost. Passt die Adresse, gibt es Details, sonst die knappe Meldung.
Für ausführliche Fehlermeldungen im Browser eignet sich der Kontext Development. Der Kontext allein schaltet die Details aber nicht ein. Mara setzt dafür in der additional.php displayErrors auf 1. Im Modul Settings bietet Configuration Presets dafür das Paket Debug an.
Live gilt das Gegenteil:
- displayErrors steht auf 0, so wie im Paket Live.
- devIPmask enthält höchstens wenige interne Adressen oder bleibt leer. Der Stern als Wert würde Debug-Ausgaben für alle freigeben.
- Fehler werden protokolliert, und jemand schaut regelmäßig ins Log.
Wo landen die Fehler? In einer Composer-Installation schreibt TYPO3 sie in den Ordner var/log, in eine Datei mit dem Namen typo3, einem Unterstrich und einem kurzen Hash. Zusätzlich zeigt das Modul Log unter Administration Einträge aus der Tabelle sys_log.
Der Seiten-Cache
Ein Cache ist ein Zwischenspeicher. Er hält schon berechnete Ergebnisse vor, damit der nächste Aufruf schneller geht. Die Daten selbst bleiben in der Datenbank, der Cache ersetzt oder löscht sie nicht.
Der wichtigste Cache für Integratoren ist der Seiten-Cache. Er liegt auf dem Server, nicht im Browser der Besucher. Beim ersten Aufruf rendert TYPO3 die Seite und speichert das Ergebnis, danach liefert es die gespeicherte Fassung aus.
Daraus folgt ein typisches Rätsel: Ein Redakteur ändert eine Überschrift, aber der Besucher sieht noch die alte, weil sie noch im Cache liegt. Meist leert TYPO3 beim Speichern den Cache der betroffenen Seite automatisch. Steht der Inhalt aber auch auf einer anderen Seite, etwa als Teaser auf der Startseite, bleibt deren Cache stehen.
Leeren von Hand geht auf zwei Arten:
- Über die Seite selbst, mit dem Blitz-Symbol im Modul Layout, leerst du nur den Cache dieser einen Seite.
- Über das Blitz-Menü in der oberen Leiste leert Flush frontend caches die Seiten-Caches der ganzen Installation. Danach muss jede Seite neu gerendert werden, das erzeugt eine Weile mehr Last auf dem Server. Benutzer und Extensions bleiben unberührt.
Flush all caches leert zusätzlich weitere Caches. Den gründlichsten Weg bietet das Modul Maintenance, und auf der Kommandozeile gibt es cache:flush.
Wie lange bleibt eine Seite im Cache? Den Standard für alle Seiten setzt config.cache_period in TypoScript, in Sekunden. Seit TYPO3 14.3.1 ist der Standard 31536000 Sekunden, also 365 Tage. Davor war es ein Tag, also 86400 Sekunden, und so steht es noch in vielen Anleitungen. Für eine einzelne Seite stellst du die Dauer in den Seiteneigenschaften im Reiter Behaviour ein, neben den Cache-Tags der Seite. Ein Wert größer 0 in der Seite hat Vorrang vor config.cache_period.
Inhalte mit Start- oder Stoppzeit verkürzen die Lebensdauer von selbst, damit sie pünktlich erscheinen oder verschwinden.
Ganz abschalten kannst du den Seiten-Cache mit config.no_cache auf 1. Das ist nur beim Entwickeln sinnvoll, denn dann wird jede Seite bei jedem Aufruf komplett neu gerendert. Ein Häkchen „Nicht cachen“ in den Seiteneigenschaften gibt es schon seit TYPO3 9 nicht mehr.
Gezielt leeren und dynamische Bereiche
Auf der Startseite der Musikschule stehen Teaser der nächsten Konzerte. Die Konzerte selbst pflegt die Redaktion in einem Ordner. Speichert sie dort ein Konzert, leert TYPO3 nur den Cache dieses Ordners. Die Startseite zeigt weiter den alten Stand.
Die Lösung ist TCEMAIN.clearCacheCmd im Page TSconfig. Es leert beim Speichern zusätzliche Seiten-Caches. Erlaubt sind diese Werte, auch mehrere mit Komma getrennt:
- Seiten-IDs, zum Beispiel 1 für die Startseite.
- Das Schlüsselwort pages für alle Seiten-Caches.
- Das Schlüsselwort all für alle Caches.
- Das Präfix cacheTag mit Doppelpunkt und einem Tag-Namen.
Cache-Tags sind Markierungen an Cache-Einträgen. Über einen Tag leerst du viele Einträge auf einmal, ohne ihre Seiten-IDs zu kennen. Eine Seite bekommt einen Tag über das Feld Cache-Tags in ihren Seiteneigenschaften oder in TypoScript über die stdWrap-Funktion addPageCacheTags.
TCEMAIN.clearCacheCmd = 1, cacheTag:konzerte- Mara trägt bei der Startseite und der Seite Veranstaltungen im Feld Cache-Tags den Wert konzerte ein.
- Im Page TSconfig des Konzert-Ordners setzt sie clearCacheCmd auf cacheTag:konzerte.
- Speichert die Redaktion ein Konzert, verlieren alle so markierten Seiten ihren Cache und zeigen beim nächsten Aufruf den neuen Termin.
Den ganzen Cache jede Nacht zu leeren oder das Caching abzuschalten wäre die schlechtere Wahl.
Dynamische Bereiche: In der Kopfzeile der Startseite soll eine Uhrzeit stehen, die bei jedem Aufruf stimmt. Dafür gibt Mara diesen Bereich als COA_INT oder USER_INT aus. Diese ungecachten Objekte stehen im Cache nur als Platzhalter. TYPO3 rendert sie bei jedem Aufruf nach, der Rest der Seite bleibt gecacht. config.no_cache würde dagegen die ganze Seite ungecacht lassen und die Leistung verschlechtern.
page.30 = COA_INT
page.30.10 = TEXT
page.30.10.data = date:H:iDas Admin Panel
Das Admin Panel ist eine Leiste am unteren Rand der Frontend-Seiten. Es kommt aus der Systemerweiterung adminpanel, als Composer-Paket typo3/cms-adminpanel. Sehen können es nur Benutzer, die im selben Browser im Backend angemeldet sind.
Einschalten braucht zwei Teile:
- Im TypoScript setzt du
config.admPanelauf 1. Dann erscheint das Panel für angemeldete Admins. - Andere Backend-Benutzer brauchen zusätzlich
admPanel.enableim User TSconfig, für sich selbst oder für ihre Gruppe. MitadmPanel.enable.allauf 1 bekommen sie alle Bereiche, mitadmPanel.enable.previewoderadmPanel.enable.cachenur einzelne.
Admins haben admPanel.enable.all standardmäßig. Für Redakteure reicht config.admPanel allein also nicht, Adminrechte brauchen sie aber auch nicht.
Die Leiste zeigt direkt TypoScript-Meldungen, Ladezeit und Speicherverbrauch, Fehler und Warnungen sowie Anzahl und Dauer der SQL-Abfragen, aber keine Besucherzahlen. Aufgeklappt hat sie diese Bereiche:
- Info zeigt die Seiten-ID, den Seitentyp, ob die Seite aus dem Cache kam und die Zahl der USER_INT-Objekte.
- TypoScript zeigt die Zeitmessung des TypoScript-Renderings.
- Debug zeigt alle SQL-Abfragen mit Dauer sowie Log-Einträge und Events.
- Preview bietet „Simulate time“ für geplante Inhalte, „Simulate user group“ für geschützte Inhalte und das Einblenden versteckter Seiten und Datensätze.
- Cache schaltet das Caching ab, leert den Cache der aktuellen Seite oder den ganzen Frontend-Cache.
Über die Schaltfläche Settings setzt du die Einstellungen dieser Bereiche, etwa die simulierte Zeit. Den Application Context kann das Panel nicht simulieren, nur Zeit und Benutzergruppe.
Das Wichtigste in Kürze
- TYPO3 schreibt die Systemwerte in die settings.php. Die additional.php wird danach geladen, gewinnt und nimmt eigene Logik und Zugangsdaten auf.
- Der Kontext kommt aus der Umgebungsvariablen TYPO3_CONTEXT, ohne Angabe gilt Production, auch auf der Kommandozeile.
- Die Module unter System sehen nur System Maintainer, im Kontext Development jeder Admin.
- Das Install Tool ohne Backend braucht das Passwort und die Datei ENABLE_INSTALL_TOOL, die nach einer Stunde verfällt, außer sie enthält KEEP_FILE.
- adminOnly auf 2 lässt nur Admins ins Backend und die Kommandozeile weiterlaufen. LOCK_BACKEND sperrt alle aus.
- displayErrors auf 0 verbirgt Fehler. Beim Standard minus 1 entscheidet devIPmask.
- config.cache_period setzt die Standard-Lebensdauer, die Seiteneigenschaften gehen vor.
- clearCacheCmd und Cache-Tags leeren beim Speichern gezielt weitere Seiten, COA_INT und USER_INT halten Bereiche dynamisch.
- Das Admin Panel braucht config.admPanel und für Nicht-Admins admPanel.enable im User TSconfig.
Begriffe
- Application Context
- Umgebung, in der TYPO3 läuft, also Production, Development oder Testing.
- System Maintainer
- Admin, der die Wartungsmodule unter System öffnen darf.
- ENABLE_INSTALL_TOOL
- Merkerdatei, die den eigenständigen Zugang zum Install Tool für eine Stunde öffnet.
- LOCK_BACKEND
- Merkerdatei, die das Backend für alle Benutzer sperrt.
- Sudo-Modus
- Erneute Passworteingabe, bevor TYPO3 eine heikle Aktion erlaubt.
- devIPmask
- Liste der IP-Adressen, die Debug-Ausgaben sehen dürfen.
- COA_INT
- Inhaltsobjekt, das bei jedem Aufruf neu gerendert wird.