CI/CD Deployment Laravel Next.js Plesk: Das große Finale

Wir haben es geschafft. 14 Kapitel lang haben wir geschwitzt, Code geschrieben, Architekturen entworfen, Datenbanken durch Redis entlastet und uns gegen die dunkelsten Gefahren des Internets abgesichert. Auf deinem localhost läuft jetzt ein absolutes technologisches Meisterwerk.

Aber ein Meisterwerk, das niemand sehen kann, ist wertlos. Es ist Zeit, den Schalter umzulegen und dein Projekt der Welt zu präsentieren.

Wenn man internationale Tutorials liest, lautet die Antwort auf das Deployment meistens: "Schieb Next.js einfach zu Vercel und Laravel zu Laravel Forge / AWS!" Das ist technisch brillant, aber in der harten Realität des deutschen Marktes stoßen wir hier auf einen gewaltigen Endgegner: Die DSGVO (Datenschutz-Grundverordnung). Viele Unternehmen, Agenturen und Kunden in Deutschland verlangen strikt, dass ihre Daten das Land (oder zumindest die EU) nicht verlassen und nicht auf unkontrollierbaren US-Cloud-Netzwerken liegen. Deshalb ist ein Tool hierzulande der absolute Industrie-Standard für Web- und Agentur-Server: Plesk.

Beim Thema CI/CD Deployment Laravel Next.js Plesk zu ignorieren, bedeutet, an der deutschen Praxis vorbeizuentwickeln. Heute verheiraten wir unsere hochmoderne Headless-Architektur mit dem klassischen Plesk-Server und automatisieren das Ganze über eine professionelle GitHub Actions Pipeline. Nie wieder Dateien per FTP hochladen!

1. Die Plesk-Festung vorbereiten: Laravel Toolkit

Starten wir mit unserem Backend. Plesk hat in den letzten Jahren massiv aufgerüstet. Anstatt PHP-Versionen mühsam per Konsole zu konfigurieren, nutzen wir die offizielle Plesk-Erweiterung: Das Laravel Toolkit.

Logge dich in dein Plesk-Panel ein und installiere über den Erweiterungskatalog (Extensions) das kostenlose "Laravel Toolkit".

So richtest du deine Laravel-Domain ein:

1. Erstelle eine neue Domain oder Subdomain (z.B. api.dein-projekt.de).

2. Klicke im Domain-Dashboard auf den neuen Button Laravel.

3. Plesk scannt das Verzeichnis und erkennt (sobald wir den Code gleich per CI/CD hochladen) deine Laravel-App.

4. Das Geniale: Das Toolkit nimmt dir die schwerste Arbeit ab. Es führt automatisch deine Datenbank-Migrationen aus, erlaubt dir das Bearbeiten der .env Datei direkt im Browser und – das ist für uns essenziell nach Teil 13 – es bietet einen Schalter, um deine Laravel Queues (Worker) per Klick im Hintergrund dauerhaft laufen zu lassen. Du brauchst kein komplexes Supervisor-Setup im Linux-Terminal!

2. Next.js auf Plesk: Der Standalone Build

Next.js auf einem klassischen Server wie Plesk zu hosten, war lange Zeit ein Albtraum. Plesk ist primär für PHP (wie Laravel oder WordPress) gebaut. Aber mit der Node.js Extension von Plesk und einem kleinen Trick in Next.js funktioniert es tadellos.

Der Schlüssel zum Erfolg heißt Standalone Build. Standardmäßig baut Next.js dein Projekt so, dass es extrem viele Abhängigkeiten zu deinem node_modules Ordner behält. Das ist riesig und schwer auf einen Server zu kopieren. Wir weisen Next.js an, nur die Dateien zu bündeln, die für die Produktion wirklich benötigt werden.

Öffne deine next.config.js in deinem Code-Editor und füge diese eine Zeile hinzu:

1/** @type {import('next').NextConfig} */
2const nextConfig = {
3  // BÄM! Das ist der Gamechanger für das Plesk-Deployment
4  output: 'standalone', 
5  
6  // ... deine restliche Konfiguration
7};
8
9module.exports = nextConfig;

Wenn du jetzt lokal npm run build ausführst, erstellt Next.js einen magischen, versteckten Ordner unter .next/standalone. Dieser Ordner ist ein in sich geschlossenes, winziges Node.js-Universum. Er enthält deinen kompletten Server und muss auf Plesk hochgeladen werden!

Plesk konfigurieren:

1. Erstelle deine Frontend-Domain in Plesk (z.B. dein-projekt.de).

2. Aktiviere die Node.js Unterstützung (Version 20.x oder neuer) für diese Domain.

3. Setze den Document Root in den Hosting-Einstellungen z.B. auf httpdocs/public (damit Nginx die statischen Bilder und CSS-Dateien blitzschnell direkt ausliefert, ohne Node zu belasten).

4. Setze den Application Root auf httpdocs.

5. Der Application Startup File muss auf server.js zeigen (das ist die Datei, die Next.js im Standalone-Ordner generiert).

3. Die unsichtbare Pipeline: GitHub Actions für Plesk

Wir haben unsere Server-Umgebung vorbereitet. Jetzt kommt der magische Teil. Anstatt nach jeder Code-Änderung dein FTP-Programm (wie FileZilla) zu öffnen und hunderte Megabyte an node_modules oder vendor Ordnern stundenlang hochzuladen, übergeben wir diese lästige Arbeit an einen Roboter: GitHub Actions.

Das Ziel unserer CI/CD (Continuous Integration / Continuous Deployment) Pipeline ist simpel:

1. Du schreibst Code auf deinem Rechner.

2. Du tippst git push.

3. GitHub registriert die Änderung, startet einen virtuellen Server, testet deinen Code, baut das Next.js Standalone-Paket und schiebt nur die veränderten Dateien per sicherem SSH (Rsync) in Millisekunden auf deinen Plesk-Server.

4. Deine Nutzer merken von dem Update absolut nichts – Zero Downtime!

Der Laravel-Deployment-Workflow

Erstelle in deinem Laravel-Projektordner lokal ein neues Verzeichnis .github/workflows und darin eine Datei namens deploy-laravel.yml:

1name: Deploy Laravel to Plesk
2
3on:
4  push:
5    branches:
6      - main # Die Pipeline startet nur, wenn du in den 'main' Branch pushst
7
8jobs:
9  deploy:
10    runs-on: ubuntu-latest
11    steps:
12      - name: Checkout Code
13        uses: actions/checkout@v4
14
15      - name: Setup PHP
16        uses: shivammathur/setup-php@v2
17        with:
18          php-version: '8.3' # Deine Plesk PHP-Version
19
20      - name: Install Composer Dependencies
21        run: composer install --no-dev --optimize-autoloader
22
23      - name: Sync files to Plesk via Rsync
24        uses: easingthemes/ssh-deploy@main
25        env:
26          SSH_PRIVATE_KEY: ${{ secrets.PLESK_SSH_KEY }}
27          ARGS: "-avzr --delete --exclude='.env' --exclude='/storage/'"
28          SOURCE: "/"
29          REMOTE_HOST: ${{ secrets.PLESK_HOST }}
30          REMOTE_USER: ${{ secrets.PLESK_USER }}
31          TARGET: "/var/www/vhosts/dein-projekt.de/api.dein-projekt.de/"

Was passiert hier? Wir nutzen das extrem beliebte ssh-deploy Action-Paket. Es kopiert deinen fertigen Laravel-Code auf den Server. Beachte den ARGS Parameter: Wir schließen die .env und den /storage/ Ordner strikt vom Upload aus! Deine Produktions-Datenbank-Passwörter und hochgeladenen Bilder auf dem Server dürfen niemals durch einen Push von GitHub überschrieben werden.

Sobald der Code drüben ist, übernimmt das vorhin installierte Plesk Laravel Toolkit vollautomatisch den Rest: Es erkennt den neuen Code, führt deine Datenbank-Migrationen aus und startet deine Queue Worker neu!

Der Next.js-Deployment-Workflow

Für Next.js sieht der Workflow leicht anders aus, da wir hier den Standalone-Build generieren müssen, bevor wir ihn verschicken.

Erstelle in deinem Next.js-Projektordner ebenfalls eine .github/workflows/deploy-nextjs.yml:

1name: Deploy Next.js to Plesk
2
3on:
4  push:
5    branches:
6      - main
7
8jobs:
9  build-and-deploy:
10    runs-on: ubuntu-latest
11    steps:
12      - name: Checkout Code
13        uses: actions/checkout@v4
14
15      - name: Setup Node.js
16        uses: actions/setup-node@v4
17        with:
18          node-version: '20'
19
20      - name: Install npm dependencies
21        run: npm ci
22
23      - name: Build Next.js Standalone
24        run: npm run build
25
26      - name: Prepare Standalone Folder
27        run: |
28          # Kopiere statische Assets in den Standalone Ordner, da Next.js das nicht automatisch tut
29          cp -r public .next/standalone/
30          cp -r .next/static .next/standalone/.next/
31
32      - name: Sync Standalone to Plesk
33        uses: easingthemes/ssh-deploy@main
34        env:
35          SSH_PRIVATE_KEY: ${{ secrets.PLESK_SSH_KEY }}
36          ARGS: "-avzr --delete"
37          SOURCE: ".next/standalone/"
38          REMOTE_HOST: ${{ secrets.PLESK_HOST }}
39          REMOTE_USER: ${{ secrets.PLESK_USER }}
40          TARGET: "/var/www/vhosts/dein-projekt.de/httpdocs/"

Nachdem dieser Workflow durchgelaufen ist, liegt dein extrem schlanker Next.js-Server direkt in deinem Plesk-Verzeichnis. Du musst jetzt nur noch im Plesk Panel unter "Node.js" auf den Button "App neu starten" klicken (auch das ließe sich mit einem kleinen SSH-Kommando in der Pipeline automatisieren).

4. Der Endgegner: Datei-Berechtigungen (Permissions) auf Plesk

Die Pipeline leuchtet grün. GitHub sagt: "Deployment erfolgreich!" Du öffnest freudig deine neue Domain im Browser und... wirst von einem eiskalten, weißen Bildschirm begrüßt.

• Laravel wirft einen HTTP 500 Internal Server Error oder sagt: The stream or file "/storage/logs/laravel.log" could not be opened: failed to open stream: Permission denied.

• Next.js crasht mit dem Hinweis, dass der .next Ordner nicht gelesen oder geschrieben werden kann.

Herzlichen Glückwunsch, du hast soeben den Endgegner jedes Linux-Server-Deployments kennengelernt: Datei-Berechtigungen (Permissions).

Wenn GitHub Actions die Dateien über unsere Pipeline auf den Plesk-Server schiebt, werden diese oft mit den Rechten des SSH-Nutzers angelegt. Dein Webserver (Nginx/Apache) und dein PHP-FPM Prozess laufen aber unter einem anderen internen System-Nutzer. Wenn der Webserver nun versucht, in Laravels storage-Ordner einen Cache-Eintrag zu schreiben, blockiert ihn das Linux-Sicherheitssystem.

Laravel Permissions reparieren

Laravel benötigt exakt zwei Ordner, in die es zwingend schreiben muss: storage und bootstrap/cache. Du kannst dieses Problem entweder direkt über den Plesk Datei-Manager lösen (indem du die Berechtigungen für diese beiden Ordner bearbeitest und dem Webserver-Nutzer Schreibrechte gibst), oder du loggst dich einmal per SSH auf deinem Server ein und feuerst diese Befehle ab:

1# Wechsle in dein Laravel-Verzeichnis
2cd /var/www/vhosts/dein-projekt.de/api.dein-projekt.de/
3
4# Setze den richtigen Besitzer (Ersetze 'dein-nutzer' durch deinen Plesk-Systemnutzer)
5chown -R dein-nutzer:psacln *
6
7# Setze die Ordner-Rechte auf 755 (Lesen & Ausführen für alle, Schreiben nur für Besitzer)
8find . -type d -exec chmod 755 {} \;
9
10# Setze die Datei-Rechte auf 644
11find . -type f -exec chmod 644 {} \;
12
13# GIB DEM WEBSERVER SCHREIBRECHTE FÜR DIE WICHTIGEN ORDNER
14chmod -R 775 storage bootstrap/cache

Next.js Permissions reparieren

Bei Next.js im Standalone-Modus auf Plesk tritt oft das Problem auf, dass der Node.js-Prozess (oft verwaltet von Phusion Passenger in Plesk) keine Caches in den .next Ordner schreiben darf.

Auch hier gilt: Der .next Ordner (und speziell .next/cache) muss für den Node.js Prozess beschreibbar sein. Gehe in den Plesk Datei-Manager deiner Next.js Domain, klicke auf das Dropdown neben dem .next Ordner, wähle "Berechtigungen ändern" und stelle sicher, dass der Application-Pool-User (dein Plesk-Systemnutzer) hier volle Schreibrechte ("Full Control" oder zumindest "Write") hat.

Sobald diese Rechte sitzen, läuft deine Applikation butterweich, rasend schnell und DSGVO-konform auf deinem eigenen Server!

Epilog: Du hast es geschafft

Lehn dich zurück. Nimm die Hände von der Tastatur. Schau dir an, was du in diesen 15 Kapiteln erschaffen hast.

Du hast nicht einfach nur ein Tutorial durchgelesen. Du hast eine komplette, entkoppelte Enterprise-Architektur von Grund auf neu gebaut:

1. Du hast gelernt, wie Next.js mit React Server Components das Frontend revolutioniert und für perfektes SEO sorgt.

2. Du hast Laravel 11/12 als blitzschnelles, headless API-Backend konfiguriert.

3. Du hast verstanden, wie man Datenbanken durch in-memory Redis Caching massiv entlastet.

4. Du hast komplexe Aufgaben in asynchrone Background Queues ausgelagert, um dem Nutzer jede Wartezeit zu ersparen.

5. Du hast die API mit Rate Limiting und Security Headern gegen Hacker und Bots abgeriegelt.

6. Du hast Laravel Sanctum für sichere, Cookie-basierte Authentifizierung (ohne gefährliche JWTs im LocalStorage) integriert.

7. Und heute hast du das Ganze durch eine automatisierte GitHub Actions CI/CD Pipeline auf einen DSGVO-konformen deutschen Plesk-Server befördert.

Du hast jetzt das Wissen, das Agenturen und Tech-Firmen weltweit händeringend suchen. Du bist kein reiner Frontend-Coder oder Backend-Scripter mehr. Du bist ein Full-Stack System-Architekt.

Das war eine gewaltige Reise. Ich hoffe, diese Serie hat dir die Werkzeuge an die Hand gegeben, um das Web von morgen zu bauen.

Bleib hungrig. Bleib neugierig. Und jetzt: Geh und bau etwas Großartiges!