WordPress und Laravel in cPanel mit Deployer deployen

Deployer automatisiert Deployments per SSH mit einem PHP-Rezept, das Sie zusammen mit dem Projekt speichern. Jede Veröffentlichung kann einen neuen Ordner vorbereiten und diese Version am Ende aktivieren. Es ist eine Alternative für alle, die ihren eigenen Deployment-Prozess pflegen möchten; wenn Sie die Einrichtung lieber im Kundenbereich vornehmen, lesen Sie Deploy+.

Diese Anleitung verwendet Deployer 8 und empfiehlt, mit einer Test-Subdomain zu beginnen. Getrennte Versionen verkürzen die Zeit des Codewechsels, die Verfügbarkeit des Dienstes hängt aber auch von Migrationen, freigegebenen Dateien, Caches und Prozessen der Anwendung ab.

Die Umgebung vorbereiten

Sie brauchen SSH-Zugang zum Hosting, ein Git-Repository, das vom Server aus erreichbar ist, und Platz für Code, Abhängigkeiten, freigegebene Dateien und mehrere Versionen. Richten Sie bei Bedarf einen Leseschlüssel für das private Repository ein.

Prüfen Sie auf Ihrem Rechner oder in Ihrer CI-Umgebung die Voraussetzungen der Installation von Deployer 8. Diese Version benötigt PHP 8.3 oder neuer, um das Tool auszuführen. Installieren Sie es als Entwicklungsabhängigkeit des Projekts und speichern Sie die Lock-Datei:

composer require --dev deployer/deployer:^8
vendor/bin/dep --version

Das PHP, das Deployer auf Ihrem Rechner ausführt, und das PHP, das die Anwendung im Hosting ausführt, sind verschiedene Umgebungen. Prüfen Sie Version und Erweiterungen beider sowie Composer, Git und die Werkzeuge, die Ihr Build braucht.

Ort und öffentliches Stammverzeichnis wählen

In den Rezepten steht {{deploy_path}}/current für den Link auf die veröffentlichte Version innerhalb des Deployment-Pfads. Deployer ersetzt {{deploy_path}} durch den konfigurierten Wert; es ist kein Pfad, den Sie wörtlich in cPanel übernehmen.

Wir verwenden /home/usuario_cpanel/apps/miapp als privates Deployment-Verzeichnis. Ersetzen Sie Benutzer, Server, SSH-Port und Repository der Beispiele durch Ihre echten Daten.

Die Struktur sieht so aus:

miapp/
  releases/   Code-Versionen
  shared/     dauerhafte Dateien
  current     Link auf die veröffentlichte Version

Das Stammverzeichnis der Testdomain muss bei Laravel current/public und bei einem klassischen WordPress current ausliefern. Prüfen Sie vor dem ersten Deployment, ob die Konfiguration Ihrer Domain diesen Pfad und symbolische Links erlaubt. Die Einschränkungen von cPanel können ein Stammverzeichnis außerhalb von public_html verhindern; auch die Hauptdomain wird nicht immer wie eine Add-on-Domain konfiguriert.

Verschieben oder löschen Sie public_html nicht, um diese Struktur zu testen: Der Ordner könnte andere Websites enthalten. Lässt die Domain den vorgesehenen Pfad nicht zu, vereinbaren Sie mit dem Support eine kompatible Konfiguration oder verwenden Sie Deploy+. Veröffentlichen Sie nicht den gesamten Laravel-Ordner, der private Dateien enthält.

Beispiel für WordPress

Dieses Beispiel setzt voraus, dass das Repository den Code eines klassischen WordPress mit Plugins und Theme enthält. Wenn Sie Bedrock oder eine andere Struktur verwenden, passen Sie Rezept und öffentliches Stammverzeichnis an.

Legen Sie im Projekt deploy.php an:

<?php
namespace Deployer;

require 'recipe/wordpress.php';

set('repository', 'git@github.com:organizacion/wordpress.git');
set('branch', 'main');
set('keep_releases', 3);
set('shared_files', ['wp-config.php']);
set('shared_dirs', ['wp-content/uploads']);
set('writable_mode', 'chmod');
set('writable_chmod_mode', '0755');
set('writable_dirs', ['wp-content/uploads']);

host('pruebas')
    ->setHostname('servidor.example.com')
    ->setRemoteUser('usuario_cpanel')
    ->setPort(93)
    ->set('deploy_path', '/home/usuario_cpanel/apps/miapp');

after('deploy:failed', 'deploy:unlock');

Bereiten Sie vorher shared/wp-config.php mit der vollständigen Konfiguration des Test-WordPress vor: Datenbank, Tabellenpräfix, Schlüssel und übrige Einstellungen der Website. Behalten Sie diese Werte bei, wenn Sie eine bestehende Installation übernehmen, und prüfen Sie übernommene absolute Pfade. Laden Sie die Zugangsdaten nicht ins Repository hoch.

Kopieren Sie die vorhandenen Bilder nach shared/wp-content/uploads und prüfen Sie ihre Berechtigungen mit dem Benutzer des Hostings. Der freigegebene Ordner muss vor der Veröffentlichung die richtigen Daten enthalten; erwarten Sie nicht, dass das Deployment die Dateien einer anderen Installation von selbst importiert.

Plugins und Themes werden in diesem Beispiel aus Git veröffentlicht. Eine Aktualisierung, die nur im WordPress-Backend erfolgt, kann mit der nächsten Version verschwinden. Legen Sie einen Aktualisierungsablauf fest, der das Repository auf dem neuesten Stand hält. Den gesamten Ordner wp-content freizugeben ist auch keine automatische Lösung: Damit ließe sich dieser Code nicht mehr zuverlässig versionieren.

Beispiel für Laravel

Das offizielle Laravel-Rezept enthält Aufgaben für Migrationen und das Neuladen von Diensten. Prüfen Sie vor der Übernahme, welche davon Ihre Anwendung braucht und zulässt. Das folgende Beispiel legt einen expliziten Ablauf ohne Migrationen und ohne Neustart von Prozessen fest, um die Veröffentlichung zuerst in der Testumgebung vorzubereiten:

<?php
namespace Deployer;

require 'recipe/laravel.php';

set('repository', 'git@github.com:organizacion/laravel.git');
set('branch', 'main');
set('keep_releases', 3);
set('shared_files', ['.env']);
set('shared_dirs', ['storage']);
set('writable_mode', 'chmod');
set('writable_chmod_mode', '0755');
set('bin/php', '/opt/alt/php83/usr/bin/php');

host('pruebas')
    ->setHostname('servidor.example.com')
    ->setRemoteUser('usuario_cpanel')
    ->setPort(93)
    ->set('deploy_path', '/home/usuario_cpanel/apps/miapp');

task('deploy', [
    'deploy:prepare',
    'deploy:vendors',
    'artisan:storage:link',
    'artisan:config:cache',
    'artisan:route:cache',
    'artisan:view:cache',
    'deploy:publish',
]);

after('deploy:failed', 'deploy:unlock');

Der Pfad zu PHP 8.3 ist ein Beispiel: Prüfen Sie, ob er existiert und composer.lock erfüllt. Konfigurieren Sie eine andere verfügbare Version, wenn das Projekt sie verlangt. Prüfen Sie auch, wie das Rezept Composer auf diesem Server ausführt.

Bereiten Sie vor dem ersten Deployment shared/.env außerhalb des öffentlichen Stammverzeichnisses vor, mit Berechtigungen, die auf den Benutzer des Kontos beschränkt sind. Verwenden Sie die Testdatenbank, deaktivieren Sie das öffentliche Debugging und behalten Sie den APP_KEY einer bestehenden Anwendung bei: Ihn neu zu erzeugen kann das Entschlüsseln von Daten verhindern und Sitzungen beenden. Erzeugen Sie einen Schlüssel nur für eine neue Installation, die noch keinen hat.

Legen Sie die Ordner an, die die Anwendung in shared/storage verwendet, einschließlich der Verzeichnisse für Sitzungen, Views und Cache, falls nötig. bootstrap/cache gehört zu jedem Release; es ist kein Unterordner von storage. Prüfen Sie, ob der Benutzer, der PHP ausführt, dort schreiben kann, wo er es muss, ohne Berechtigungen 777.

Braucht das Projekt kompilierte Assets, nehmen Sie das Ergebnis in das Artefakt auf oder fügen Sie vor der Veröffentlichung eine Build-Aufgabe hinzu. Die gezeigten Aufgaben führen kein npm aus. Ist ein Cache nicht mit Ihrer Anwendung kompatibel, korrigieren Sie deren Konfiguration oder passen Sie die Aufgabe nach einem Test an.

Das Deployment prüfen und ausführen

Auf dem Rechner, auf dem Sie Deployer installiert haben:

vendor/bin/dep deploy --plan pruebas

Prüfen Sie die Reihenfolge der Aufgaben und die Hooks der installierten Version. Der Plan hilft, unerwartete Vorgänge zu erkennen, prüft aber nicht, ob Server oder Anwendung funktionieren.

Wenn die Testumgebung bereit ist:

vendor/bin/dep deploy pruebas

Prüfen Sie das Ergebnis in der Ausgabe und öffnen Sie die Website. Testen Sie Anmeldung, eine Unterseite, Formulare, Bild-Uploads und Datenbankvorgänge. Prüfen Sie bei Laravel außerdem die geplanten Aufgaben und die Hintergrundprozesse, die Sie tatsächlich nutzen.

Schlägt eine Ausführung fehl, sehen Sie sich die erste fehlerhafte Aufgabe an. Entsperren Sie das Deployment nicht, solange ein anderer Prozess noch arbeitet, und löschen Sie keine Versionen, um Platz zu schaffen, ohne vorher festzustellen, welche aktiv ist.

Migrationen und Wechsel in die Produktion

Eine neue Version kann Schemaänderungen erfordern. Planen Sie Migrationen, die mit dem Code kompatibel sind, der während des Wechsels weiter Anfragen bedient. Ist das nicht möglich, verwenden Sie ein Wartungsfenster und ein getestetes Wiederherstellungsverfahren.

Es genügt nicht, „erst der Code, dann die Datenbank“ festzulegen: Es hängt von der Änderung ab. Fügen Sie auch kein migrate:fresh, das Tabellen löscht, in das Deployment einer Installation mit Daten ein.

Bewahren Sie vor dem Wechsel in die Produktion eine wiederherstellbare Kopie von Dateien und Datenbank auf, testen Sie das Rezept und bereiten Sie die Änderung des Stammverzeichnisses der Domain vor. Für die erste Veröffentlichung gibt es kein früheres Release, zu dem Sie zurückkehren könnten.

Zu einer früheren Version zurückkehren

Wenn Sie eine kompatible frühere Version aufbewahren, können Sie das Rollback auslösen:

vendor/bin/dep rollback pruebas

Prüfen Sie danach die Website und ihre wichtigsten Vorgänge. Das Rollback ändert den veröffentlichten Code; es stellt weder die Datenbank wieder her noch setzt es die freigegebenen Dateien auf ihren früheren Stand zurück. Eine Migration oder ein Skript, das sie geändert hat, braucht ein eigenes Wiederherstellungsverfahren.

Aufbewahrte Releases belegen Speicherplatz und ersetzen keine Backups. Passen Sie ihre Aufbewahrung an die Größe des Projekts und den verfügbaren Spielraum für den Aufbau der nächsten Version an.

Weitere verfügbare Aufgaben finden Sie im WordPress-Rezept und im Laravel-Rezept der Version, die Sie installiert haben. Verwenden Sie in einem Shared Hosting Deployment-Aufgaben mit Ihrem Benutzer; Rezepte zur Server-Provisionierung erfordern Rechte, die dieses Konto nicht hat.