Laravel-Projekt übernehmen: Praxis-Checkliste vor Wartung und Weiterentwicklung

Bei einer Laravel-Übernahme braucht das neue Team belastbare Nachweise für Setup, Betrieb, Deployment und Wiederherstellung. Fehlende Details fallen sonst häufig erst beim ersten eigenen Release auf: Ein Queue Worker benötigt einen Neustart, der Dateispeicher läuft über ein fremdes Konto oder der Rückweg zur letzten funktionierenden Version ist ungeklärt. Die folgende Prüfung zeigt, ob sich die Anwendung ohne verborgenes Wissen betreiben und weiterentwickeln lässt.

Behandle die Übernahme als Betriebsübergabe

Ein technisch ordentliches Repository ist hilfreich, beantwortet aber noch keine der entscheidenden Betriebsfragen. Es sagt dir nicht automatisch, welche externen Dienste beteiligt sind, wo Produktionszugänge liegen oder welche Prozesse dauerhaft auf dem Server laufen. Ebenso wenig beweist eine erreichbare Startseite, dass E-Mails, Zahlungen, Importe und Hintergrundjobs funktionieren.

Lege für die Prüfung eine Tabelle mit fünf Spalten an:

• Prüfpunkt: Was soll geklärt oder getestet werden?
• Status: vorhanden, fehlt, ungeklärt oder getestet
• Nachweis: Dokument, Screenshot, Testprotokoll, Kontoeinladung oder ausführbarer Ablauf
• Verantwortlicher: Wer liefert die Information oder behebt die Lücke?
• Nächste Aktion: Was muss konkret passieren und bis wann?

„Sollte vorhanden sein“ ist dabei kein Status. Ein Zugang gilt erst als geprüft, wenn die richtige Person sich anmelden kann. Ein Deployment gilt erst als nachvollziehbar, wenn es jemand aus dem neuen Team ausgeführt hat. Und ein Backup ist noch keine bestätigte Wiederherstellung.

Auftrag, Systemgrenzen und kritische Abläufe klären

Bevor du Konfigurationsdateien und Paketversionen untersuchst, brauchst du ein knappes Betriebsbild. Sonst prüfst du möglicherweise sehr gründlich einen Nebenbereich, während ein geschäftskritischer Prozess unerkannt bleibt.

Dokumentiere zunächst:

• Welchen Geschäftszweck erfüllt die Anwendung?
• Welche Nutzergruppen arbeiten damit?
• Welche Funktionen müssen jederzeit beziehungsweise zu festgelegten Zeiten verfügbar sein?
• Welche bekannten Fehler, manuellen Umgehungen und offenen Änderungen gibt es?
• Welche Daten kommen in das System und wohin werden sie übertragen?
• Welche Teile gehören ausdrücklich zum vereinbarten Wartungs- oder Weiterentwicklungsumfang?
• Wer entscheidet bei fachlichen Fragen, Releases und Störungen?

Ein einfaches Beispiel: Eine Verwaltungsoberfläche kann erreichbar sein, obwohl der nächtliche Import seit Tagen nicht läuft. Wenn dieser Import Bestellungen oder Bestände verarbeitet, gehört er in die Liste der kritischen Abläufe. Die Oberfläche allein reicht als Betriebsnachweis nicht aus.

Erwartetes Ergebnis: Du hast eine abgegrenzte Liste der kritischen Funktionen, Schnittstellen und Ansprechpartner. Das neue Team weiß, was nach einem Deployment getestet werden muss und welche Ausfälle zuerst behandelt werden.

Zugänge und dauerhafte Kontrolle sichern

Bei Konten geht es nicht nur darum, irgendwo ein Passwort zu finden. Entscheidend ist, ob der Auftraggeber oder eine dauerhaft zuständige Organisation administrativen Zugriff besitzt und weitere Teammitglieder selbst hinzufügen kann. Ob daraus rechtliches Eigentum oder eine Herausgabepflicht folgt, lässt sich durch eine technische Prüfung nicht feststellen. Diese Fragen gehören bei Bedarf in die vertragliche oder rechtliche Klärung.

Prüfe mindestens die Zugänge zu folgenden Bereichen:

• Git-Repository einschließlich Organisation, Deploy Keys und gegebenenfalls CI/CD-System
• Hosting-Konto, Server, Cloud-Ressourcen oder Verwaltungsoberfläche des Betriebs
• Domain, DNS und Zertifikatsverwaltung
• Produktions-, Staging- und gegebenenfalls weiteren Datenbanken
• Datei- oder Objektspeicher
• Transaktions-E-Mail und weitere Versanddienste
• Zahlungsanbieter, externe APIs und Webhook-Plattformen
• Fehlerprotokollierung, Verfügbarkeitsprüfung und Benachrichtigungskanäle
• Backups und Speicherort der Sicherungen

Kontrolliere zusätzlich, welche E-Mail-Adresse als Kontoinhaber oder Wiederherstellungskontakt hinterlegt ist. Persönliche Postfächer ehemaliger Dienstleister sind für dauerhafte Projektkonten ungünstig. Wo Mehrfaktor-Authentifizierung eingesetzt wird, müssen auch Wiederherstellungsverfahren und Zuständigkeiten geklärt sein. Zugangsdaten selbst gehören nicht als Klartext in die Prüftabelle.

Nach Abschluss der Übergabe solltest du nicht mehr benötigte Zugriffe entfernen und relevante Zugangsdaten kontrolliert wechseln. Plane diese Rotation so, dass laufende Deployments, Webhooks und Hintergrundprozesse nicht versehentlich ihre Berechtigungen verlieren.

Erwartetes Ergebnis: Für jedes betriebsrelevante System existiert ein bestätigter administrativer Zugang, ein verantwortlicher Kontakt und ein dokumentierter Wiederherstellungsweg.

Den technischen Steckbrief des Projekts erstellen

Jetzt wird festgehalten, unter welchen technischen Voraussetzungen die Anwendung tatsächlich läuft. Versionsangaben aus einer alten Projektbeschreibung reichen dafür nicht. Maßgeblich sind Repository, Sperrdateien, Serverkonfiguration und ausgeführte Laufzeit.

Der Steckbrief sollte mindestens enthalten:

• Laravel-Version und PHP-Version
• Datenbanksystem und relevante Version
• Webserver und PHP-Betriebsart
• Node.js-Version, Paketmanager und Build-Prozess, sofern Frontend-Ressourcen gebaut werden
• zentrale Composer- und NPM-Pakete
• Cache-, Session- und Queue-Treiber
• lokale Entwicklungsumgebung und Staging-Umgebung
• bekannte Upgrade-Hindernisse oder nicht mehr gepflegte Abhängigkeiten

Framework, Laufzeit und Pakete müssen gemeinsam betrachtet werden. Die offizielle Deployment-Dokumentation für Laravel 13 nennt beispielsweise PHP 8.3 als Mindestversion. Daraus folgt nicht, dass jedes übernommene Projekt sofort Laravel 13 einsetzen muss. Es zeigt aber, warum eine isolierte Angabe wie „läuft mit PHP“ für Wartungsplanung und Upgrades wertlos ist.

Die Sperrdateien composer.lock und – je nach verwendetem Paketmanager – etwa package-lock.json, pnpm-lock.yaml oder yarn.lock gehören ebenfalls in die Prüfung. Sie halten die konkret aufgelösten Paketstände fest. Fehlen sie, kann eine Neuinstallation andere Abhängigkeiten erhalten als das laufende System.

Erwartetes Ergebnis: Du kannst die eingesetzten Versionen belegen und erkennst, welche Abhängigkeiten vor dem nächsten regulären Upgrade untersucht werden müssen.

Das Projekt aus einer sauberen Umgebung starten

Die wichtigste Dokumentationsprüfung ist ein praktischer Versuch: Eine Person, die das Projekt bisher nicht eingerichtet hat, startet es anhand der vorhandenen Anleitung. Eine bereits eingerichtete Entwicklerumgebung ist kein ausreichender Nachweis. Dort können globale Werkzeuge, alte Konfigurationswerte oder lokale Dateien vorhanden sein, ohne dass diese Abhängigkeiten dokumentiert wurden.

Für einen reproduzierbaren Start brauchst du in der Regel:

• ein aktuelles README mit Installations- und Startanweisungen
• die benötigten PHP- und Node-Versionen
• installierbare Abhängigkeiten auf Basis der Sperrdateien
• eine dokumentierte Datenbankeinrichtung
• ausführbare Migrationen
• geeignete Testdaten oder eine beschriebene Alternative
• einen nachvollziehbaren Build für Frontend-Ressourcen
• eine Liste aller erforderlichen Umgebungsvariablen

Eine echte Produktionsdatenbank sollte nicht beiläufig zur lokalen Starthilfe werden. Kläre stattdessen, ob Seed-Daten, Fixtures oder eine kontrolliert aufbereitete Testkopie verfügbar sind. Dabei müssen die für das Projekt geltenden Vorgaben zum Umgang mit personenbezogenen und vertraulichen Daten berücksichtigt werden.

Die unverschlüsselte .env-Datei gehört nicht in die Versionsverwaltung. Als übertragbare Dokumentation der benötigten Variablen sieht die Laravel-Konfigurationsdokumentation eine gepflegte .env.example mit Platzhaltern vor. Diese Beispieldatei sollte alle benötigten Variablennamen enthalten, aber keine echten Passwörter, Schlüssel oder Tokens.

Teste anschließend dieselbe Einrichtung in einer Staging-Umgebung, soweit eine solche Umgebung zum Projekt gehört oder für die Übernahme eingerichtet wird. Lokal erfolgreich zu starten beweist noch nicht, dass Webserver, Netzwerkzugriffe, Speicher und dauerhafte Prozesse unter realistischen Bedingungen zusammenspielen.

Erwartetes Ergebnis: Ein neues Teammitglied kann das Projekt mit der Dokumentation aufsetzen. Offene Schritte, fehlende Testdaten und manuelle Sonderfälle sind konkret erfasst.

Produktionskonfiguration und Servergrenzen prüfen

Nach dem reproduzierbaren Start folgt die Frage, ob die Anwendung korrekt und sicherheitsbewusst ausgeliefert wird. Dazu gehört zunächst der Webroot, also das Verzeichnis, das der Webserver öffentlich bereitstellt. Laravel-Anwendungen sollen über das öffentliche Verzeichnis und dessen public/index.php ausgeliefert werden. Eine Bereitstellung aus dem Projektstamm kann sensible Dateien erreichbar machen, wie die Laravel-Dokumentation zum Deployment erläutert.

Prüfe außerdem:

• APP_ENV entspricht der Umgebung.
• APP_DEBUG ist in Produktion deaktiviert.
• Schreibrechte bestehen nur dort, wo die Anwendung sie benötigt.
• Storage-Verknüpfungen und persistente Verzeichnisse sind dokumentiert.
• Cache, Sessions und Queues verwenden die vorgesehenen Treiber.
• Konfigurationswerte und Secrets werden kontrolliert bereitgestellt.
• Logdateien sind auffindbar und ihre Aufbewahrung ist geklärt.

Aktivierte Debug-Ausgaben können sensible Konfigurationswerte offenlegen. Deshalb soll APP_DEBUG laut Laravel-Deployment-Dokumentation in der Produktionsumgebung deaktiviert sein. Prüfe den tatsächlich wirksamen Wert und nicht nur eine Beispieldatei im Repository.

Erwartetes Ergebnis: Die Produktionsumgebung liefert ausschließlich das vorgesehene öffentliche Verzeichnis aus. Umgebungsmodus, Debug-Einstellung, Speicherorte und Laufzeitkonfiguration sind überprüft.

Datenflüsse und externe Abhängigkeiten erfassen

Viele Laravel-Anwendungen bestehen betrieblich aus mehr als Webserver und Datenbank. Ein Formular versendet E-Mails, ein Zahlungsanbieter meldet Statusänderungen per Webhook zurück, Dateien liegen in einem separaten Speicher und ein nächtlicher Import holt Daten aus einem Drittsystem. Ohne diese Übersicht kann ein Team die Anwendung zwar öffnen, aber nicht verlässlich betreiben.

Erfasse für jede externe Abhängigkeit:

• Zweck und betroffener Geschäftsprozess
• verantwortliches Konto und technischer Ansprechpartner
• verwendete Zugangsdaten oder Zertifikate, ohne deren Werte in die Liste zu kopieren
• Test- und Produktionsumgebung
• eingehende und ausgehende Daten
• Webhook-URLs, erlaubte Absender oder Netzwerkfreigaben
• Verhalten bei Zeitüberschreitungen, Fehlern oder Nichtverfügbarkeit
• Möglichkeit für einen kontrollierten Funktionstest

Kontrolliere auch Import- und Exportwege, die außerhalb des normalen Webverkehrs liegen. Dazu zählen manuell hochgeladene Dateien, SFTP-Verzeichnisse, geplante Exporte und Befehle, die nur über die Kommandozeile ausgeführt werden. Solche Abläufe sind leicht zu übersehen, weil sie im Browser nicht sichtbar werden.

Erwartetes Ergebnis: Jede externe Verbindung hat einen dokumentierten Zweck, Zugang, Testweg und Verantwortlichen. Kritische Abläufe lassen sich nach einer Änderung gezielt prüfen.

Queues, Scheduler und dauerhafte Prozesse sichtbar machen

Der Browser zeigt nur Anfragen, die unmittelbar beantwortet werden. Laravel kann daneben Jobs, geplante Aufgaben und dauerhaft laufende Dienste verwenden. Bei einer Übernahme musst du deshalb sowohl im Code als auch auf dem Server prüfen, welche Prozesse tatsächlich benötigt werden.

Suche unter anderem nach:

• Jobs, Queue-Verbindungen und fehlgeschlagenen Queue-Aufgaben
• geplanten Befehlen und Aufgaben des Laravel Schedulers
• Horizon, falls es im Projekt eingesetzt wird
• Reverb oder anderen WebSocket-Diensten
• Octane und zugehörigen Anwendungsprozessen
• eigenen Artisan-Befehlen
• Import-, Export- und Synchronisationsprozessen
• Prozessmanagern und deren Konfiguration

Queue Worker sind langlebige Prozesse. Sie übernehmen geänderten Anwendungscode nicht automatisch und müssen deshalb im Deployment neu geladen beziehungsweise neu gestartet werden. Anschließend sorgt üblicherweise ein Prozessmanager dafür, dass sie weiterlaufen. Dieses Verhalten beschreibt die Laravel-Dokumentation zu Queues.

Für den Laravel Scheduler genügt serverseitig grundsätzlich ein einzelner Cron-Eintrag, der schedule:run jede Minute aufruft; die eigentlichen Aufgaben werden in der Anwendung definiert. Prüfe deshalb beide Seiten: den Servereintrag und den Anwendungscode. Die Dokumentation zum Task Scheduling beschreibt diesen Aufbau.

Für jeden dauerhaften Prozess brauchst du vier Antworten: Wie wird er gestartet? Wie wird er nach einem Deployment neu geladen? Wie erkennst du einen Fehler? Wer reagiert darauf? Halte die Antworten im Übergabepaket und in den Betriebsanweisungen fest.

Erwartetes Ergebnis: Alle benötigten Hintergrundprozesse sind benannt, auf dem Server auffindbar und mit Start-, Neustart- sowie Fehlerverfahren dokumentiert.

Deployment und Rückweg praktisch testen

Eine Liste von Shell-Befehlen ist noch kein getesteter Deployment-Prozess. Das neue Team sollte den vollständigen Ablauf zunächst in Staging ausführen. Dabei wird sichtbar, welche manuellen Annahmen bisher nur im Kopf des alten Projektteams existierten.

Der dokumentierte Ablauf sollte klären:

1. Wie wird eine freigegebene Version ausgewählt?
2. Wie werden Code und Abhängigkeiten bereitgestellt?
3. Wie und wann laufen Datenbankmigrationen?
4. Wie werden Frontend-Ressourcen gebaut oder übernommen?
5. Welche Laravel-Caches werden aufgebaut oder geleert?
6. Wie werden Queue Worker und andere langlebige Dienste neu geladen?
7. Welche Prüfungen folgen unmittelbar nach dem Deployment?
8. Wie erfolgt der Rückweg, wenn die neue Version nicht funktioniert?

Laravel empfiehlt für Produktions-Deployments das Caching von Konfiguration, Events, Routen und Views über den Befehl optimize. Außerdem müssen langlebige Dienste den neuen Code laden. Beides ist in der Deployment-Dokumentation von Laravel beschrieben. Ob und an welcher Stelle diese Schritte in deinem Projekt ausgeführt werden, gehört in den konkreten Ablauf.

Ein Rückweg muss die Datenbank berücksichtigen. Code lässt sich häufig auf eine frühere Version setzen, während bereits ausgeführte Migrationen oder verarbeitete Daten bestehen bleiben. Deshalb sollte vor riskanten Änderungen geklärt sein, welche Schritte umkehrbar sind, welche Sicherung benötigt wird und wer über einen Abbruch entscheidet.

Erwartetes Ergebnis: Das neue Team hat ein Deployment in Staging vollständig durchgeführt und den Rückweg für relevante Fehlerbilder beschrieben. Ungeprüfte manuelle Schritte sind als Risiko markiert.

Nach dem Deployment mehr als die Startseite prüfen

Ein erfolgreicher HTTP-Aufruf beweist nur einen kleinen Teil des Betriebs. Nach jeder Veröffentlichung brauchst du einen kurzen, projektspezifischen Funktionstest. Er sollte die zuvor erfassten kritischen Abläufe abdecken.

Eine sinnvolle Prüfreihenfolge ist:

1. Anwendung bootet und zentrale Seiten sind erreichbar.
2. Anmeldung und Berechtigungen funktionieren mit einem Testkonto.
3. Datenbankzugriffe und eine ungefährliche Schreiboperation funktionieren.
4. Dateien lassen sich lesen und – soweit vorgesehen – schreiben.
5. Eine Test-E-Mail oder eine vergleichbare Benachrichtigung wird verarbeitet.
6. Ein kontrollierter Queue Job läuft vollständig durch.
7. Geplante Aufgaben sind aktiv und protokollierbar.
8. Kritische externe Schnittstellen beantworten einen vorgesehenen Test.
9. Logs und Fehlerbenachrichtigungen zeigen keine neuen Auffälligkeiten.

Laravel stellt standardmäßig eine Health-Route unter /up bereit. Sie antwortet bei erfolgreichem Booten der Anwendung mit HTTP 200 und kann um anwendungsspezifische Prüfungen erweitert werden, wie die Laravel-Dokumentation zur Health Route erläutert. Eine erfolgreiche /up-Antwort ersetzt jedoch keinen fachlichen Funktionstest. Die Route kann grün sein, während ein externer Dienst oder ein Queue-Prozess ausfällt.

Erwartetes Ergebnis: Es existiert ein kurzer, wiederholbarer Testablauf für Webanwendung, Datenbank, Speicher, externe Dienste und Hintergrundjobs.

Backups durch eine Wiederherstellung belegen

Bei der Übergabe solltest du dokumentieren, was gesichert wird, wie häufig der vorgesehene Sicherungsprozess läuft, wo die Sicherungen gespeichert werden und wer Zugriff darauf hat. Dazu gehören je nach Anwendung nicht nur Datenbanken, sondern auch hochgeladene Dateien oder andere persistente Daten.

Der entscheidende Nachweis ist eine kontrollierte Wiederherstellung in einer getrennten Umgebung. Dabei prüfst du:

• ob die benötigte Sicherung auffindbar und lesbar ist
• ob Datenbank und Dateien zueinander passen
• welche Schritte und Zugangsdaten für die Wiederherstellung nötig sind
• ob die Anwendung mit den wiederhergestellten Daten startet
• ob ausgewählte Datensätze und Dateien tatsächlich verfügbar sind

Ein Protokoll „Backup erfolgreich“ bestätigt zunächst nur, dass ein Sicherungslauf keinen gemeldeten Fehler hatte. Es bestätigt nicht automatisch, dass die Anwendung daraus wiederhergestellt werden kann.

Erwartetes Ergebnis: Eine Wiederherstellung wurde in einer geeigneten Umgebung durchgeführt und als Ablauf dokumentiert. Offene Abhängigkeiten und manuelle Schritte sind bekannt.

Risiken mit einer Ampel priorisieren

Nach der Prüfung wird die Liste wahrscheinlich länger sein als das verfügbare Budget. Die Ampel hilft dir, betriebliche Blockaden von normaler technischer Pflege zu trennen.

Rot: Übernahme oder Release blockiert

• Produktionszugänge fehlen oder sind nicht verifizierbar.
• Das Projekt lässt sich nicht reproduzierbar starten.
• Der Deployment-Prozess ist unbekannt oder nur vom bisherigen Entwickler ausführbar.
• Kritische Secrets liegen ungeschützt im Repository.
• Erforderliche Hintergrundprozesse sind nicht identifizierbar.
• Für kritische Daten gibt es keinen geklärten Wiederherstellungsweg.

Gelb: Betrieb möglich, Risiko muss eingeplant werden

• Die Dokumentation ist unvollständig, der Ablauf wurde aber nachvollzogen.
• Abhängigkeiten sind veraltet oder ein Upgrade-Hindernis ist absehbar.
• Staging weicht relevant von Produktion ab.
• Externe Dienste lassen sich nicht kontrolliert testen.
• Funktionstests sind nur teilweise dokumentiert.

Grün: nachgewiesen und übertragbar

• Zugänge sind bestätigt und Verantwortliche benannt.
• Ein frisches Setup funktioniert nach Anleitung.
• Deployment und anschließende Prüfungen wurden ausgeführt.
• Hintergrundprozesse sind dokumentiert und kontrollierbar.
• Die Wiederherstellung wurde praktisch nachvollzogen.

Grün bedeutet nicht, dass die Anwendung fehlerfrei oder modern ist. Es bedeutet, dass der jeweilige Betriebsaspekt nachgewiesen und für das neue Team handhabbar ist. Codequalität, fachliche Erweiterungen und größere Upgrades können danach separat bewertet werden.

Unbekannte Projekte nicht sofort pauschal warten

Wenn zentrale Punkte zu Beginn ungeklärt sind, lässt sich der Wartungsaufwand kaum seriös abgrenzen. In diesem Fall ist eine vorgeschaltete, klar begrenzte Übernahmeprüfung sinnvoller als ein Wartungsversprechen auf unbekannter Grundlage.

Das Ergebnis dieser Prüfung sollte kein langer Bericht für die Ablage sein, sondern ein arbeitsfähiges Übergabepaket:

• technischer Steckbrief
• Zugangs- und Verantwortungsmatrix ohne geheime Werte
• Setup-Anleitung
• Deployment- und Rückweg-Beschreibung
• Liste der Hintergrundprozesse
• Übersicht externer Dienste und Datenflüsse
• Ablauf der Funktionstests
• priorisierte Risikoliste mit nächsten Aktionen

Erst danach lässt sich entscheiden, ob reguläre Wartung beginnen kann, zunächst technische Altlasten beseitigt werden müssen oder einzelne Betriebsrisiken ausdrücklich außerhalb des Auftrags bleiben.

Fazit: Übernommen ist ein Laravel-Projekt erst nach dem Betriebsnachweis

Repository, Serverzugang und eine laufende Startseite sind lediglich der Anfang einer Laravel-Übernahme. Belastbar wird die Übergabe, wenn das neue Team die Anwendung aus einer sauberen Umgebung starten, ihre Abhängigkeiten benennen, ein Deployment ausführen, Hintergrundprozesse kontrollieren und eine Wiederherstellung nachvollziehen kann.

Nutze für jeden Prüfpunkt die vier Zustände vorhanden, fehlt, ungeklärt oder getestet und verlange einen konkreten Nachweis. Damit wird aus einer diffusen technischen Bestandsaufnahme eine entscheidbare Betriebsübergabe. Du erkennst vor dem ersten Release, welche Lücken den Betrieb blockieren, welche Risiken ins Budget gehören und welche Punkte normale Weiterentwicklung sind.