Laravel auf einem Hosting mit cPanel installieren (Laravel 13 und 12)

Sie können Laravel auf einem Hosting mit cPanel mit Composer und SSH-Zugang installieren. In dieser Anleitung legen wir ein neues Projekt an, bereiten seine Datenbank vor, konfigurieren die Domain so, dass sie nur den Ordner public veröffentlicht, und richten die Bausteine ein, die eine Anwendung in Produktion meist braucht: Scheduler, Queues, Sessions, Cache und bei Bedarf Horizon und WebSockets.

Wenn Sie bereits eine Anwendung in einem Repository haben, müssen Sie keine neue anlegen: Verbinden Sie das Repository mit Deploy+ und folgen Sie dieser Anleitung ab dem Abschnitt zur Datenbank.

1. PHP-Version wählen und die des Terminals prüfen

Laravel 13 benötigt PHP 8.3 oder höher, Laravel 12 PHP 8.2 oder höher, jeweils im Rahmen dessen, was Ihre Abhängigkeiten unterstützen. Die Version der Website wählen Sie im PHP-Selector; bei einer mit Deploy+ veröffentlichten Website wird sie in der .htaccess Ihres Repositorys festgelegt, wie unter PHP-Version mit Deploy+ erklärt.

Öffnen Sie SSH oder das cPanel-Terminal und prüfen Sie, welche Version die Befehle ausführt:

php -v
composer --version

Das php des Terminals ist nicht immer die Version Ihrer Website: Wir haben Konten gesehen, in denen PHP 8.1 antwortete, während der Selector auf 8.4 stand. Wenn sie nicht übereinstimmt, rufen Sie das Binärprogramm Ihrer Version über seinen vollständigen Pfad auf, zum Beispiel /opt/alt/php84/usr/bin/php artisan migrate, und führen Sie Composer damit aus:

/opt/alt/php84/usr/bin/php "$(command -v composer)" install

Im Rest der Anleitung schreiben wir der Kürze halber php: Ersetzen Sie es durch den vollständigen Pfad, wenn Ihr Terminal eine andere Version liefert. Im Cron und in dauerhaften Prozessen verwenden Sie immer den vollständigen Pfad.

Zu den Anforderungen von Laravel gehören Ctype, cURL, DOM, Fileinfo, Filter, Hash, Mbstring, OpenSSL, PCRE, PDO, Session, Tokenizer und XML; die gewählte Datenbank benötigt zusätzlich ihren PHP-Treiber. Erweiterungen werden pro Version aktiviert: Wenn Composer ext-fileinfo is missing meldet, aktivieren Sie sie in der Version, die den Befehl ausführt. Überspringen Sie die Prüfungen nicht mit --ignore-platform-reqs: Inkompatible Abhängigkeiten zu installieren, bringt die Anwendung nicht zum Laufen.

Auch die Werte jeder Version wie memory_limit, max_execution_time, upload_max_filesize oder max_input_vars passen Sie an die Bedürfnisse Ihrer Anwendung an: im Tab Limits der Website-Ansicht im Kundenbereich oder unter Options im cPanel-Selector, wie in PHP: Version, Module und Konfiguration wählen beschrieben. max_execution_time begrenzt nur Webanfragen: Artisan, der Scheduler und die Worker haben diese Höchstdauer nicht.

2. Das Projekt außerhalb des öffentlichen Verzeichnisses anlegen

Legen Sie vom Stammverzeichnis Ihres Kontos aus einen neuen Ordner an, der noch nicht existiert:

cd ~
composer create-project laravel/laravel mi-proyecto "^13.0"
cd mi-proyecto
php artisan --version
composer check-platform-reqs

Die Artisan-Prüfung muss Laravel 13 anzeigen; die Composer-Prüfung muss die Anforderungen der Umgebung bestätigen. Führen Sie create-project nicht über einer bestehenden Website aus.

Wenn die Anwendung oder eine Integration Laravel 12 verlangt, verwenden Sie einen anderen neuen Ordner mit composer create-project laravel/laravel mi-proyecto-12 "^12.0". Laut offiziellem Zeitplan erhält es Sicherheitskorrekturen bis zum 24. Februar 2027; lesen Sie bei der Wahl der Version die Support-Richtlinie von Laravel. Für ein bestehendes Projekt verwenden Sie seine composer.lock mit composer install; ersetzen Sie es nicht durch eine Neuinstallation und wechseln Sie die Hauptversion nicht, ohne das Upgrade zu prüfen.

Wenn Sie ein Starter-Kit (React, Vue, Svelte oder Livewire) bevorzugen, installieren Sie den offiziellen Installer mit composer global require laravel/installer, fügen Sie den Pfad, den composer global config bin-dir --absolute ausgibt, zum PATH hinzu und verwenden Sie laravel new otro-proyecto in einem neuen Ordner. Lesen Sie laravel new --help, bevor Sie Optionen automatisieren.

3. Die Datenbank konfigurieren

Eine Neuinstallation kann mit SQLite beginnen, wenn PHP den Treiber dafür hat. Für MySQL legen Sie die Datenbank und ihren Benutzer mit dem Datenbank-Assistenten von cPanel an. Wenn Sie mit Deploy+ deployen, kann es beim Verbinden des Repositorys die Datenbank anlegen und die Verbindung in die .env schreiben.

Bearbeiten Sie die .env im Projekt mit den tatsächlichen Daten dieser Datenbank:

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=miusuario_proyecto
DB_USERNAME=miusuario_app
DB_PASSWORD="sustituye_por_la_clave_de_la_base"

Verwenden Sie die vollständigen Namen, die cPanel anzeigt, einschließlich Präfix. Veröffentlichen Sie die .env nicht und laden Sie sie nicht ins Repository hoch. Führen Sie im neuen Projekt aus:

php artisan config:clear
php artisan migrate

Wenn Sie eine Anwendung mit vorhandenen Daten deployen, prüfen Sie die Migrationen und behalten Sie ein Backup, bevor Sie sie anwenden. Verwenden Sie nicht migrate:fresh: Es löscht die Tabellen.

4. Nur den Ordner public veröffentlichen

Die Domain muss /home/tu_usuario/mi-proyecto/public ausliefern, nicht /home/tu_usuario/mi-proyecto. So bleiben Konfigurationsdateien und privater Code außerhalb des Web-Stammverzeichnisses.

Bei einer Addon-Domain oder Subdomain prüfen Sie ihr Verzeichnis unter cPanel > Domains > Manage und wählen, sofern die Konfiguration es erlaubt, den Ordner public des Projekts. Verschieben Sie index.php nicht ins Stammverzeichnis, um diesen Schritt zu umgehen.

Bei der Hauptdomain verwendet cPanel normalerweise public_html. Wenn Sie dieses Verzeichnis durch einen Link auf das public von Laravel ersetzen müssen, planen Sie vorher, was es enthält, sein Backup und den Weg zurück; benennen Sie public_html nicht um und löschen Sie es nicht, ohne zu prüfen, ob dort bereits eine Website oder andere Domains liegen. Mit Deploy+ veröffentlicht die Laravel-Vorlage den Ordner public des Repositorys in dem Ordner, den Sie wählen und der beim ersten Deployment leer sein muss.

5. Die Anwendung vorbereiten und prüfen

Konfigurieren Sie in der .env die tatsächliche URL und deaktivieren Sie das öffentliche Debugging:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://ihredomain.com

Die Installation muss einen Schlüssel APP_KEY haben. In einem neuen Projekt ohne Schlüssel erzeugen Sie einen mit php artisan key:generate. Erzeugen Sie ihn in einer bestehenden Anwendung nicht neu: Verschlüsselte Daten könnten sonst unlesbar werden.

Wenn Ihr Projekt Vite verwendet, bauen Sie seine Ressourcen mit einer Node.js-Version, die zu seiner package.json passt: npm install und npm run build bei einer Neuinstallation; npm ci und npm run build bei Deployments mit package-lock.json. Node.js finden Sie im Paketmanager, es dient zum Bauen; siehe Node.js zum Bauen von Assets.

Prüfen Sie, ob storage und bootstrap/cache für die Anwendung beschreibbar sind, ohne pauschal 777-Rechte zu setzen, und führen Sie php artisan optimize aus.

Öffnen Sie die Domain per HTTPS und prüfen Sie Startseite, Unterseiten und Funktionen, die die Datenbank abfragen. Prüfen Sie auch, dass /.env die Datei nicht ausliefert. Bei einem 500-Fehler sehen Sie in storage/logs/laravel.log und in den Logs des Hostings nach; aktivieren Sie nicht das öffentliche Debugging, um den Fehler allen Besuchern anzuzeigen.

6. Den Scheduler einplanen

Wenn Sie das Projekt mit Deploy+ veröffentlichen, erledigt der Assistent das für Sie: Lassen Sie Den Laravel-Scheduler einplanen aktiviert, und die Aufgabe wird nach dem ersten Deployment hinzugefügt, wie unter Deploy+ erklärt. Prüfen Sie sie trotzdem mit php artisan schedule:list.

Andernfalls fügen Sie unter cPanel > Cron Jobs eine Aufgabe hinzu, die jede Minute mit dem PHP Ihrer Anwendung läuft:

* * * * * /opt/alt/php84/usr/bin/php /home/tu_usuario/mi-proyecto/artisan schedule:run > /dev/null 2>&1

Ersetzen Sie php84 durch Ihre Version und den Pfad durch den Ihres Projekts; mit Deploy+ ist es /home/tu_usuario/deploy/nombre-repo/current/artisan. Verwenden Sie weder /usr/local/bin/php noch einfach php: Das können andere PHP-Versionen mit anderen Erweiterungen sein, und der Scheduler startet die geplanten Aufgaben mit demselben PHP, mit dem er selbst startet.

Bevor Sie die Aufgabe aktiv lassen, führen Sie denselben Befehl von Hand aus, ohne die Ausgabe zu verwerfen, und prüfen Sie php artisan schedule:list. Mehr zum Cron finden Sie unter Cron-Aufgaben in cPanel.

7. Queues

Seit Laravel 11 speichert ein neues Projekt die Jobs in der Datenbank (QUEUE_CONNECTION=database). In einem älteren Projekt legen Sie zuerst die Tabelle mit php artisan queue:table an und migrieren. Je nach Tarif unterscheidet sich, wer sie verarbeitet.

Mit dauerhaften Prozessen (Avanza, Max und Elastic)

Legen Sie unter Tools > Prozesse einen Queue-Worker mit dem Ordner der Anwendung und ihrer PHP-Version an. Er bleibt in Betrieb, verarbeitet jeden Job, sobald er eintrifft, und startet von selbst neu, wenn er abstürzt. Wenn Sie eine Version mit Deploy+ veröffentlichen, startet er von selbst neu, um den neuen Code zu laden. Alle Details stehen unter dauerhafte Prozesse.

Ohne dauerhafte Prozesse

In jedem Tarif kann der Scheduler jede Minute einen Worker starten, der die offenen Jobs verarbeitet und sich dann beendet. In routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('queue:work --stop-when-empty --tries=3 --max-time=300')
    ->everyMinute()
    ->withoutOverlapping(10)
    ->runInBackground();

withoutOverlapping(10) verhindert, dass zwei Worker gleichzeitig laufen, und gibt die Sperre nach 10 Minuten frei, falls einer mittendrin abbricht; runInBackground() sorgt dafür, dass die übrigen geplanten Aufgaben pünktlich laufen. Ein Job kann bis zu einer Minute warten, bevor er verarbeitet wird.

Wenn Sie nicht vom Scheduler abhängen möchten, erledigt eine Cron-Aufgabe mit flock dasselbe ohne Überschneidungen:

* * * * * cd /home/tu_usuario/mi-proyecto && /usr/bin/flock -n /home/tu_usuario/.cola-mi-proyecto.lock /opt/alt/php84/usr/bin/php artisan queue:work --stop-when-empty --max-time=300 > /dev/null 2>&1

In beiden Fällen prüfen Sie fehlgeschlagene Jobs mit php artisan queue:failed.

8. Sessions, Cache und Redis

Wo was gespeichert wird:

• Sessions: in der Datenbank (SESSION_DRIVER=database) in jedem Tarif; ab Avanza auch im persistenten Redis (redis).
• Queues: in der Datenbank (QUEUE_CONNECTION=database) in jedem Tarif; ab Avanza auch im persistenten Redis (redis).
• Cache: in der Datenbank (CACHE_STORE=database) oder in Redis Cache, in jedem Tarif.
• Horizon: nur mit persistentem Redis, ab Avanza.

Die beiden Redis-Varianten dienen nicht demselben Zweck:

• Redis Cache, in allen Tarifen, ist nur ein Cache: Nach einem Neustart ist er leer, und wenn er voll ist, verwirft er Schlüssel. Verwenden Sie ihn für CACHE_STORE=redis und nie für Sessions oder Queues. Konfiguration unter Redis als Objekt-Cache.
• Persistentes Redis, ab Avanza, speichert seine Daten auf der Festplatte und verwirft sie nicht: Es ist der Ort für Queues, Sessions und Horizon. Es wird im Paketmanager aktiviert und über einen Socket Ihres Kontos verbunden. Konfiguration unter persistentes Redis.

Sie können beide gleichzeitig verwenden: den Cache in Redis Cache und Queues und Sessions im persistenten Redis. Sessions in der Datenbank sind seit Laravel 11 die Standardoption und funktionieren in jedem Tarif; in einem älteren Projekt legen Sie die Tabelle mit php artisan session:table an.

9. Horizon

Horizon benötigt Queues in Redis und einen laufenden Prozess, funktioniert also ab dem Tarif Avanza: Aktivieren Sie das persistente Redis, setzen Sie QUEUE_CONNECTION=redis, installieren Sie laravel/horizon und legen Sie einen dauerhaften Prozess vom Typ Horizon an. Passen Sie maxProcesses in config/horizon.php an die Ressourcen Ihres Tarifs an. Mit Deploy+ startet Horizon nach dem Aktivieren jeder Version von selbst neu; wenn Sie anders veröffentlichen, führen Sie php artisan horizon:terminate aus, sobald der neue Code an seinem Platz ist. Die Schritte stehen unter persistentes Redis für Queues, Sessions und Horizon.

Horizon auf Redis Cache ist nicht sicher: Wenn dieser Cache geleert wird oder voll läuft, gehen Jobs verloren.

10. Broadcasting und WebSockets

Reverb bieten wir auf dem Hosting nicht an: Es ist ein Server, der auf einem eigenen Port lauscht, und solche Programme unterstützen wir nicht, wie unter dauerhafte Prozesse erklärt. Für Benachrichtigungen und Echtzeit-Events verbinden Sie Ihre Anwendung mit einem Dienst, der das Pusher-Protokoll unterstützt, etwa Pusher Channels oder Ably, die Laravel von Haus aus unterstützt. Ihre Anwendung sendet nur ausgehende HTTPS-Anfragen, und die Browser verbinden sich mit dem Dienst. Vergleich und Konfiguration unter WebSockets in Laravel.

Was nicht auf das Hosting passt

• Octane: Hier liefert LiteSpeed PHP aus, und Octane benötigt einen eigenen Anwendungsserver davor (Swoole, RoadRunner oder FrankenPHP).
• Reverb oder ein anderer eigener WebSocket-Server: Verwenden Sie einen Pusher-kompatiblen Dienst.
• Node.js als Server: Node dient zum Bauen von Assets. Das SSR von Inertia benötigt einen laufenden Node-Server; ohne ihn rendert Inertia wie gewohnt im Browser.
• Systemdienste oder Root-Zugang. Wenn Ihr Projekt sie benötigt, schildern Sie uns den Fall, bevor Sie bestellen.

Livewire, Inertia, Filament, Sanctum, Socialite oder Scout funktionieren ohne Besonderheiten.

Weitere Änderungen mit Deploy+ veröffentlichen

Sobald das Projekt in Git liegt, veröffentlicht Deploy+ jede Version in einem eigenen Ordner, mit gemeinsamen Dateien und Versionen, zu denen Sie zurückkehren können. Ein Deployment-Skript für Laravel:

composer install --no-dev --optimize-autoloader --no-interaction
php artisan migrate --force
php artisan optimize

Wenn Sie Assets bauen, ergänzen Sie die npm-Zeilen aus der Deploy+-Anleitung. queue:restart oder horizon:terminate sind nicht nötig: Nach dem Aktivieren jeder Version, und auch bei der Rückkehr zu einer früheren, startet Deploy+ die dauerhaften Prozesse der Anwendung neu. Ein Zurücksetzen des Codes macht Datenbankänderungen nicht automatisch rückgängig: Planen Sie Ihre Migrationen mit Blick auf diesen Unterschied.

Das empfohlene Skript, welche Prozesse das Hosting unterstützt und der Vergleich mit einem VPS sind unter Hosting für Laravel mit Deploy+ zusammengefasst.

Referenzen: Laravel-Installation, Queues und Empfehlungen zum Deployment.