Sie haben ein PHP-Projekt geerbt. Es läuft seit Jahren produktiv, aber niemand traut sich, es lokal zu starten. Die einzige Doku ist ein Kollege, der vor drei Jahren gegangen ist. Genau hier fängt jede seriöse Modernisierung an: nicht mit einem Rewrite, sondern damit, dass Sie das System auf Ihrem Rechner reproduzierbar zum Laufen bringen. Ein System, das seit Jahren zuverlassig arbeitet, ist kein Müll. Es ist der Beweis, dass die Fachlogik funktioniert. Das Problem ist fast nie diese Logik, sondern der Code und die Infrastruktur drumherum.
Docker ist dafür das richtige Werkzeug. Es kapselt die exakte Laufzeitumgebung, sodass PHP 5.6, eine alte MySQL-Version und eine bestimmte Apache-Konfiguration nebeneinander existieren, ohne Ihr System zu verseuchen. In diesem Beitrag geht es konkret darum, wie Sie ein Legacy-PHP-Projekt mit Docker lokal lauffähig machen.
Warum Legacy PHP und Docker so gut zusammenpassen
Der klassische Schmerz bei Altprojekten ist die Umgebung. Der Code erwartet PHP 5.6 mit der alten mysql_*-Extension, Ihr Mac hat aber PHP 8.3. Lokal installieren können Sie das kaum noch sauber. Docker löst das, indem es die Umgebung von Ihrem Host trennt.
Der entscheidende Punkt: Sie ändern beim Dockerisieren zunächst keine Zeile Fachlogik. Sie bauen nur die Umgebung nach, in der der Code ohnehin schon läuft. Das macht diesen Schritt so risikoarm. Sie schaffen sich eine reproduzierbare Basis, auf der jede spätere Migration überhaupt erst messbar und testbar wird.
Wie sieht ein minimales Legacy-PHP-Docker-Setup aus?
Ein lauffähiges Setup für ein typisches Alt-Projekt besteht aus drei Bausteinen: einem PHP-Container (oft mit Apache), einer Datenbank und einem docker-compose.yml, das beides verbindet. Fangen Sie bewusst mit der PHP-Version an, die in Produktion läuft, nicht mit der, die Sie gern hätten.
Ein Dockerfile für eine alte Anwendung kann so aussehen:
FROM php:5.6-apache
RUN docker-php-ext-install mysqli pdo pdo_mysql
RUN a2enmod rewrite
COPY . /var/www/html/
Die offiziellen php-Images auf Docker Hub gibt es bis zurück zu sehr alten Versionen. Für PHP 5.x sind diese Images inzwischen nicht mehr offiziell gepflegt, funktionieren für lokale Entwicklung aber weiterhin. Das docker-compose.yml ergänzt die Datenbank:
services:
app:
build: .
ports: ["8080:80"]
volumes: [".:/var/www/html"]
db:
image: mysql:5.7
environment:
MYSQL_ROOT_PASSWORD: root
Das Volume auf den aktuellen Ordner sorgt dafür, dass Ihre Codeänderungen sofort im Container sichtbar sind, ohne neu zu bauen. Das ist beim Debuggen von Altcode Gold wert.
Die richtige PHP- und Datenbank-Version treffen
Bevor Sie bauen, brauchen Sie zwei Fakten aus der Produktion: die exakte PHP-Version und die Datenbank-Version. Fragen Sie diese nicht ins Blaue, sondern lesen Sie sie aus. Auf dem Produktivserver liefert php -v und in der Datenbank SELECT VERSION(); die Wahrheit. Ein Setup, das mit MySQL 8 statt 5.7 startet, kann durch geänderte Default-Collations oder den strengeren SQL-Mode subtile Fehler produzieren, die es in Produktion nie gab.
Prüfen Sie auch die geladenen PHP-Extensions. Ältere Anwendungen hängen oft an spezifischen Modulen wie gd, mcrypt, soap oder intl. Ein phpinfo() aus Produktion zeigt Ihnen die vollständige Liste. Genau diese Extensions installieren Sie dann im Dockerfile nach.
Typische Stolpersteine beim Dockerisieren von Altprojekten
Beim ersten Start wird meist nicht alles sofort grün. Die häufigsten Ursachen sind überschaubar und gut lösbar:
- Hartcodierte Pfade und Hosts: Alte Configs enthalten oft
localhostals Datenbank-Host. Im Compose-Netzwerk heißt die Datenbank aberdb. Passen Sie die Verbindungskonfiguration an oder setzen Sie sie per Umgebungsvariable. - Dateirechte: Cache-, Log- oder Upload-Verzeichnisse müssen für den Webserver-User (oft
www-data) schreibbar sein. Ein fehlgeschlagenes Schreiben ins Cache-Verzeichnis ist eine der häufigsten Ursachen für einen leeren weißen Bildschirm. - Fehlende Extensions: Fatale Fehler wie
Call to undefined functiondeuten fast immer auf ein nicht installiertes PHP-Modul hin. - Ausgeschaltete Fehleranzeige: Setzen Sie lokal
display_errors = Onunderror_reporting = E_ALL. Bei Altcode wollen Sie jeden Notice sehen, sonst debuggen Sie im Dunkeln.
Daten und Sicherheit: was lokal gilt und was nicht
Für einen realistischen lokalen Start brauchen Sie einen Datenbank-Dump. Ziehen Sie ihn per mysqldump und importieren Sie ihn in den DB-Container. Ein wichtiger Hinweis zur Ehrlichkeit sich selbst gegenüber: Produktionsdaten gehören nicht ungefiltert auf Entwicklerrechner. Anonymisieren Sie personenbezogene Daten oder arbeiten Sie mit einem reduzierten, bereinigten Testdatensatz. Das ist keine Formalie, sondern DSGVO-Pflicht.
Und noch etwas Wichtiges: Ein Docker-Setup mit PHP 5.6 macht Ihre Anwendung lokal lauffähig, aber nicht sicher. Alte PHP-Versionen erhalten keine Sicherheitsupdates mehr. Das dockerisierte Legacy-System ist Ihr Ausgangspunkt für die Modernisierung, nicht das Ziel. Genau hier beginnt die eigentliche Arbeit: Version für Version anheben, mit Tests absichern, den Code drumherum erneuern, während die bewährte Fachlogik erhalten bleibt.
Der ehrliche Praxis-Tipp
Erwarten Sie nicht, dass das Projekt beim ersten docker compose up fehlerfrei startet. Das ist normal und kein Zeichen, dass mit dem Projekt etwas grundlegend falsch ist. Arbeiten Sie die Fehlermeldungen der Reihe nach ab, eine nach der anderen. Committen Sie Ihr Dockerfile und Ihr Compose-File direkt ins Repository, sobald es läuft. Damit wird die Umgebung zum Teil des Projekts und der nächste Entwickler startet in Minuten statt in Tagen. Diese reproduzierbare Basis ist die günstigste und sicherste Investition, die Sie in ein Altprojekt tätigen können, lange bevor über einen Rewrite überhaupt nachgedacht werden muss.
Wenn Sie an genau diesem Punkt feststecken oder das dockerisierte System sicher weiter modernisieren wollen, unterstützt LegacyWerk bei genau solchen Themen.
