Ok, hör zu: Ich habe im letzten Blogpost über die Kombination Docker/TYPO3 gewettert, und dabei bleibe ich auch. Trotzdem gibt es mehrere gute Gründe, TYPO3 mit Docker zu entwickeln, und die Vorteile überwiegen die Probleme.
In diesem Blogpost zeige ich dir, wie du die perfekte TYPO3-Entwicklungsumgebung für ein Sitepackage aufsetzt, in einer Multidomain-Umgebung mit Docker, docker-compose, Xdebug und TYPO3 11.5.
Der Stack
Bevor wir loslegen, das lassen wir laufen:
- einen Nginx-Container als Reverse Proxy
- einen PHP-FPM-Container mit Xdebug
- einen MySQL-Container
- TYPO3 11.5, installiert über Composer
Nginx routet den Traffic anhand des Hostnamens, sodass site-one.local und site-two.local beide auf dieselbe TYPO3-Instanz zeigen können und sich trotzdem wie völlig getrennte Seiten verhalten.
Hosts-Datei
Zuerst das Wichtigste: Dein Browser hat keine Ahnung, was site-one.local ist. Du musst deinem Betriebssystem sagen, dass es diese Domainnamen auf localhost routen soll. Das machst du über die Hosts-Datei.
Unter Linux und Mac findest du sie unter /etc/hosts. Unter Windows versteckt sie sich in C:\Windows\System32\drivers\etc\hosts. Öffne sie mit Admin- bzw. Root-Rechten und trag deine lokalen Domains ein:
127.0.0.1 site-one.local
127.0.0.1 site-two.local
Wenn du jetzt site-one.local in deinen Browser tippst, routet deine Maschine den Request an localhost – wo dein Docker-Setup lauscht. Nginx übernimmt ab da und liefert anhand des Hostnamens die richtige TYPO3-Seite aus.
In deiner Nginx-Konfiguration legst du für jede Domain einen eigenen Server-Block an:
server {
listen 80;
server_name site-one.local;
root /var/www/html/public;
index index.php;
# ... Rest deiner Nginx-Konfiguration
}
server {
listen 80;
server_name site-two.local;
root /var/www/html/public;
index index.php;
# ... Rest deiner Nginx-Konfiguration
}
Nutz eine einheitliche Namenskonvention für deine lokalen Domains – etwa .local – und zieh sie im ganzen Team durch. Dokumentier sie in der README des Projekts, damit eine neue Entwicklerin in fünf Minuten läuft und nicht in fünf Stunden.
Cache abschalten
TYPO3s Caching ist großartig für Produktion. Für die Entwicklung ist es ein Albtraum. Du änderst etwas in deinem TypoScript und nichts passiert, weil TYPO3 fröhlich eine gecachte Version ausliefert. Das ändern wir.
Prüf in deiner AdditionalConfiguration.php den Application Context und schalt alles ab, was dich ausbremst:
if (getenv('TYPO3_CONTEXT') === 'Development') {
$GLOBALS['TYPO3_CONF_VARS']['FE']['debug'] = 1;
$GLOBALS['TYPO3_CONF_VARS']['SYS']['devIPmask'] = '*';
$GLOBALS['TYPO3_CONF_VARS']['SYS']['displayErrors'] = 1;
$GLOBALS['TYPO3_CONF_VARS']['SYS']['clearCacheSystem'] = 1;
}
Nutz das nicht in Produktion!!!
Und setz die Umgebungsvariable in deiner docker-compose.yml:
services:
php:
environment:
- TYPO3_CONTEXT=Development
Damit zeigt TYPO3 Fehler an, überspringt das Frontend-Caching und benimmt sich generell wie ein gut erzogenes Entwicklungswerkzeug.
In der Entwicklung kannst du ein anderes Log-Level fahren, das dir hilft, Fehler früh zu finden – setz displayErrors auf 1 und devIPmask auf *, und TYPO3 zeigt dir alles, was schiefläuft.
Debugger
Ich habe schon darüber geschrieben, warum du einen Debugger nutzen solltest. Sparen wir uns also die Missionierung und bringen Xdebug direkt mit Docker und PhpStorm zum Laufen – der Teil, an dem die meisten Entwickler aufgeben. Tu es nicht. Es lohnt sich.
Stell zuerst sicher, dass Xdebug in deinem PHP-Container installiert ist. In deinem Dockerfile:
RUN pecl install xdebug && docker-php-ext-enable xdebug
Dann konfigurierst du Xdebug so, dass es sich zurück zu deiner Host-Maschine verbindet. Der Trick dabei ist host.docker.internal – Docker löst das automatisch auf die IP deiner Host-Maschine auf:
[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
Unter Linux funktioniert host.docker.internal nicht out of the box. Ergänz das in deiner docker-compose.yml:
extra_hosts:
- "host.docker.internal:host-gateway"
Geh in PhpStorm auf Settings → PHP → Debug und setz den Port auf 9003. Dann leg unter Settings → PHP → Servers einen Server mit deiner lokalen Domain an und konfigurier die Path Mappings – mappe deinen lokalen Projektwurzelordner auf /var/www/html im Container.
Das Path Mapping ist der Teil, den alle falsch machen. Dein lokales /home/user/myproject muss auf /var/www/html im Container zeigen. Mach das falsch, und Xdebug verbindet sich, aber PhpStorm hat keine Ahnung, wo es den Breakpoint setzen soll.
Drück auf „Listen for PHP Debug Connections", setz einen Breakpoint, lad deine Seite neu. PhpStorm hält genau dort an. Kein var_dump() mehr – ab jetzt debuggst du wie ein Profi.