Laravel von GitHub mit Git und .cpanel.yml in cPanel deployen

Diese Anleitung erklärt den manuellen Ablauf mit Git und .cpanel.yml von cPanel für eine Laravel-Anwendung. Wenn Sie Repositorys, Skripte, Versionen und Webhooks im Kundenbereich verwalten möchten, verwenden Sie Deploy+.

Das cPanel-Beispiel aktualisiert einen Arbeitsklon. Es erzeugt von sich aus keine isolierten Releases und garantiert nicht, dass die Website während einer Aktualisierung ohne Unterbrechung erreichbar bleibt.

Zugang und Projekt vorbereiten

Aktivieren Sie SSH und richten Sie einen eigenen Leseschlüssel für das private Repository ein. Prüfen Sie den Fingerabdruck von GitHub und verwenden Sie keine Identität erneut, die Zugriff auf andere Projekte hat.

Arbeiten Sie zuerst mit einer Testdomain und einer Testdatenbank. Das Repository sollte den Code und composer.lock enthalten, aber keine Passwörter, keine Produktions-.env und keine von Benutzern hochgeladenen Dateien.

Geben Sie unter cPanel > Git Version Control > Create die SSH-URL, einen privaten Pfad wie ~/repositories/laravel (ersetzen Sie ~ durch das Verzeichnis Ihres Kontos, wenn das Formular einen absoluten Pfad verlangt) und einen aussagekräftigen Namen ein. Wenn Sie einen SSH-Alias für den Schlüssel verwenden, nutzen Sie ihn auch in der URL des Klons.

Prüfen Sie Branch und Inhalt, bevor Sie das Deployment einrichten.

Die Aufgaben festlegen

Legen Sie .cpanel.yml im Stammverzeichnis des Repositorys an. Damit die Prüfungen beisammen bleiben und der Vorgang stoppt, wenn ein Befehl fehlschlägt, rufen Sie ein versioniertes Skript auf:

---
deployment:
  tasks:
    - /bin/bash /home/usuario_cpanel/repositories/laravel/deploy/cpanel.sh

Ein Beispiel für deploy/cpanel.sh:

#!/bin/bash
set -euo pipefail
cd /home/usuario_cpanel/repositories/laravel

PHP_BIN=/opt/alt/php83/usr/bin/php
COMPOSER_BIN=/opt/cpanel/composer/bin/composer

test -x "$PHP_BIN"
test -f "$COMPOSER_BIN"
test -f composer.lock
test -f .env

"$PHP_BIN" "$COMPOSER_BIN" install --no-dev --no-interaction --prefer-dist --optimize-autoloader
"$PHP_BIN" artisan config:cache
"$PHP_BIN" artisan view:cache
"$PHP_BIN" artisan route:cache

Ersetzen Sie den Benutzer und prüfen Sie die Pfade von PHP und Composer in Ihrem Konto. PHP 8.3 ist nur der Beispielwert: Der Kommandozeilen-Interpreter muss mit Ihrer Anwendung und der Version, die die Website ausliefert, kompatibel sein. Verwenden Sie composer update nicht, um Abhängigkeiten direkt in der Produktion aufzulösen.

Bereiten Sie die private .env, die Datenbank und die persistenten Verzeichnisse vor, bevor Sie das Skript ausführen. Wenn Sie eine bestehende Anwendung migrieren, behalten Sie ihren APP_KEY bei. Setzen Sie APP_DEBUG=false. Ergänzen Sie den Build der Assets, den das Projekt braucht, oder veröffentlichen Sie sie bereits kompiliert aus einer kompatiblen Umgebung.

Datenbankmigrationen brauchen einen eigenen, getesteten Plan. Sie sind hier nicht automatisch enthalten: Ein Fehler im Code macht keine Migration rückgängig und stellt keine Daten wieder her.

Nur den Ordner public veröffentlichen

Laravel muss über seinen Ordner public ausgeliefert werden, nicht über das Stammverzeichnis des Repositorys. Prüfen Sie das Document Root der Domain und die Pfade, die der Server erlaubt.

Verwenden Sie für eine Add-on-Domain oder Subdomain einen Pfad, den cPanel zulässt. Muss die Hauptdomain public_html beibehalten, bereiten Sie die passende Veröffentlichung mit dem Support oder dem Deployment-Tool vor. Löschen oder benennen Sie diesen Ordner nicht komplett um, ohne andere Websites, Dateien und Dienste zu prüfen, die davon abhängen.

Sichern Sie vor einer Änderung der Veröffentlichung eine Kopie der Website und der Datenbank und legen Sie fest, wie Sie das vorherige Ziel wiederherstellen. Testen Sie das Projekt zuerst an seinem Testort.

Aktualisieren und deployen

Öffnen Sie im Repository in cPanel Manage > Pull or Deploy:

1. Führen Sie Update from Remote aus, um den Code abzurufen.
2. Prüfen Sie Commit und Branch.
3. Führen Sie Deploy HEAD Commit für die Aufgaben aus .cpanel.yml aus.
4. Verfolgen Sie das Log bis zum Abschluss und testen Sie die Website.

Vom Remote aktualisieren und die Aufgaben ausführen sind zwei getrennte Vorgänge. Liefert die Website den Klon direkt aus, kann schon der erste Schritt sichtbare Dateien ändern, auch wenn Sie den zweiten noch nicht ausgeführt haben.

Die entsprechende lokale Deployment-Anfrage lautet:

/usr/local/cpanel/bin/uapi --output=jsonpretty VersionControlDeployment create \
  repository_root='/home/usuario_cpanel/repositories/laravel'

Ein result.status gleich 1 bestätigt, dass cPanel die Anfrage angenommen hat. Verfolgen Sie den Job und seinen log_path, bis das Endergebnis feststeht; verstehen Sie es nicht als „die Anwendung funktioniert bereits“.

Automatisieren, ohne dass sich Jobs überschneiden

Ein Push zu GitHub startet den Pull in cPanel nicht von selbst. Zum Automatisieren brauchen Sie einen Empfänger oder einen Prozess, der ihn plant. Deploy+ bietet diese Integration, ohne dass Sie den Empfänger selbst bauen müssen.

Betreiben Sie einen eigenen, prüfen Sie die Signatur des Anbieters, das Repository und den Branch, bevor Sie Arbeit in die Warteschlange stellen. Verwenden Sie Befehle und Pfade aus Ihrer Konfiguration und halten Sie eine Sperre, bis das Deployment wirklich abgeschlossen ist. Wer nur den Aufruf sperrt, der einen Job in die Warteschlange stellt, verhindert nicht, dass sich zwei spätere Jobs überschneiden.

Veröffentlichen Sie keine URL, die beim Aufruf Befehle ausführt, und übernehmen Sie den Inhalt des Webhooks nicht direkt in die Shell. Protokollieren Sie Zustellung, Commit und Ergebnis ohne Geheimnisse.

Prüfen und wiederherstellen

Testen Sie Startseite, eine dynamische Route, Anmeldung, Formulare und Assets. Prüfen Sie Logs und Prozesse, die den neuen Code laden müssen. Schlägt das Deployment fehl, ermitteln Sie, welche Aufgaben bereits ausgeführt wurden, bevor Sie es wiederholen.

Ein früheres Verzeichnis oder einen früheren Commit wiederherzustellen setzt weder Datenbanken noch .env noch gemeinsam genutzte Dateien zurück. Für häufige Aktualisierungen, bei denen Sie zwischen Versionen wechseln müssen, ziehen Sie Deploy+ oder eine Release-Strategie mit getestetem Rollback in Betracht.