# LUF – Deployment (Stand 2026-11-15) Abgeleitet aus dem Shinkan-Verfahren, siehe [Bestandsaufnahme_Deployment_2026-11-15.md](Bestandsaufnahme_Deployment_2026-11-15.md). **Status: Anwendung U0 liegt im Repo. Ein Deploy ist erst gelaufen, wenn ein Push auf `develop` den Workflow grün durchlaufen hat.** Lokal gibt es PHP 8.4 und Node. Docker liegt auf dem Runner, nicht auf dem Entwicklungsrechner. ## Ablauf | Auslöser | Workflow | Schritte | |---|---|---| | Push auf `feature/**` | `ci-feature.yml` | Commit klonen, Test-Image bauen, Pint und `php artisan test` im Wegwerf-Container | | Push auf `develop` | `deploy-test.yml` | Tests, dann Deploy Test (`luf-test`, Port 3011) | | Push auf `main` | `deploy-prod.yml` | Tests auf genau diesem Commit, dann Deploy Prod (`luf-prod`, Port 3010) | - Der Deploy-Job hat `needs: test`. Sind die Tests rot, läuft kein Deploy. - Deployt wird der getestete Commit (`github.sha`), nicht der jeweils neueste Stand des Branches. - `scripts/deploy.sh`: Konfigurationsprüfung, Portkonflikt-Prüfung, Build, DB starten, `migrate --force`, Start, Health (`/up` und Datenbankzugriff). Bei Fehler Rollback auf den letzten erfolgreichen Image-Tag (`.last_good_tag`). Der Deploy legt keinen Demokatalog an. `DemoCatalogSeeder` bleibt für die Testsuite; der Bestand der Testinstanz wird in der Verwaltung gepflegt. - Ein Deploy gleichzeitig pro Host (`flock`), alte Images werden bis auf die letzten Tags entfernt. - **Rollback betrifft nur den Code.** Migrationen werden nicht zurückgenommen. Migrationen müssen daher abwärtskompatibel sein (erst ergänzen, später entfernen). ## Env-Datei ändern (zum Beispiel Mail, `APP_URL`) 1. `/etc/luf/prod.env` bzw. `/etc/luf/test.env` auf llm-node bearbeiten (Besitzer `llmadmin`, Rechte `640`). 2. In Gitea unter Actions den letzten Lauf von „Deploy Production“ bzw. „Deploy Test“ erneut starten. Der Lauf baut denselben Stand und erzeugt App, Queue und Scheduler mit der geänderten Datei neu; die Datenbank bleibt. 3. Prüfen: `docker exec luf-prod-app-1 printenv ` zeigt den neuen Wert. Ein Neustart (`docker restart`) reicht nicht, die Umgebung wird nur beim Erzeugen eines Containers eingelesen. **nginx findet die neue App selbst (seit 21.11.2026).** Der Web-Container löst den Namen `app` über Dockers DNS zur Laufzeit auf (`resolver 127.0.0.11` in `docker/nginx/default.conf`). Vorher war die Adresse beim Start von nginx festgeschrieben: Ein erneuter Lauf mit unverändertem Code erzeugte die App neu, nicht aber den Web-Container, und Prod antwortete mit 502, bis `luf-prod-web-1` neu gestartet wurde (20.11.2026). Ein Test (`tests/Unit/NginxConfigTest.php`) hält die Konfiguration fest. ## Stripe-Sandbox (nur Test, Etappe 1) Die Stripe-Kasse läuft ausschließlich im Testmodus und nie in Produktion. Sie ist nur aktiv, wenn `PAYMENT_DRIVER=stripe` gesetzt ist; sonst bleibt es beim Testweg (`test`). Ein Schlüssel ohne `sk_test_` (oder `rk_test_`) wird abgewiesen, in Produktion lehnt die Anwendung Stripe ganz ab. Kartendaten berühren die Anwendung nie, bezahlt wird bei Stripe. **Ablauf:** Bestellung anlegen, „Jetzt bezahlen (Stripe-Testmodus)“, Weiterleitung zur Stripe-Kasse. Freigeschaltet wird erst durch die signierte Meldung von Stripe an `POST /stripe/webhook` (Ereignis `checkout.session.completed`). Betrag und Währung werden gegen die Bestellung geprüft; wiederholte Meldungen schalten nichts doppelt frei. Eine Zahlung mit falschem Betrag oder auf eine nicht mehr offene Bestellung schaltet nichts frei und steht als Zahlung mit Status `zu_pruefen` in der Bestellung. **Einrichten (Test):** 1. In Stripe den Testmodus („Sandbox“) wählen. Unter Entwickler > API-Schlüssel den Geheimschlüssel `sk_test_…` kopieren. 2. Unter Entwickler > Webhooks einen Endpunkt anlegen: URL `https://dev.laraundfelix.de/stripe/webhook`, Ereignisse `checkout.session.completed`, `checkout.session.expired`, `checkout.session.async_payment_succeeded`, `checkout.session.async_payment_failed`. Das Signiergeheimnis `whsec_…` des Endpunkts kopieren. 3. Auf llm-node in `/etc/luf/test.env` eintragen (Rechte `640`, nichts davon ins Repo, in Commits, Logs oder Chat): ``` PAYMENT_DRIVER=stripe STRIPE_SECRET=sk_test_... STRIPE_WEBHOOK_SECRET=whsec_... STRIPE_TAX_RATE_ID=txr_... ``` `STRIPE_TAX_RATE_ID` ist optional. Verlangt Stripe für die Positionen eine Steuerangabe (Fehler „the product tax code is missing“), wird der in Stripe angelegte Steuersatz jeder Position mitgegeben. Er muss **im Preis enthalten (inklusiv)** sein: Die Bestellsumme ist der Bruttobetrag, und bei einem aufschlagenden Satz weicht der gezahlte Betrag ab, sodass die Zahlung als `zu_pruefen` festgehalten wird und nichts freischaltet. Welcher Satz gilt, entscheiden Steuer und Finance, nicht die Anwendung. 4. In Gitea den letzten Lauf von „Deploy Test“ erneut starten (siehe „Env-Datei ändern“). `docker exec luf-test-app-1 printenv PAYMENT_DRIVER` muss `stripe` zeigen. 5. Testkauf mit der Stripe-Testkarte `4242 4242 4242 4242` (beliebiges künftiges Ablaufdatum, beliebige Prüfziffer). In Stripe unter Entwickler > Webhooks > Endpunkt > Ereignisse ist jede Zustellung samt Antwortcode zu sehen. **Stolpersteine bei der ersten Einrichtung (21./22.11.2026 erlebt):** - `STRIPE_SECRET` muss der **geheime** Schlüssel `sk_test_…` sein, nicht der veröffentlichbare `pk_test_…`. Die Anwendung weist alles andere vor dem Aufruf ab („Etappe 1 erlaubt nur den Stripe-Testmodus“). - **Managed Payments** im Stripe-Konto verlangt für jedes Produkt einen Produkt-Steuercode (Fehler „Product tax code is required for Managed Payments“). Für die Sandbox wurde Managed Payments deaktiviert. Ein manueller Steuersatz (`txr_…`) ersetzt den Steuercode nicht. - Der optionale Steuersatz `STRIPE_TAX_RATE_ID` muss im Preis **enthalten** (inklusiv) angelegt sein. In der Stripe-Kasse erscheint dann „Umsatzsteuer (19 % inklusive)“ und die Gesamtsumme bleibt gleich der Bestellsumme. - Eine Änderung in `test.env` wirkt erst nach dem erneuten Lauf „Deploy Test“ (siehe oben). Die Variablennamen im Container zeigt `docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' luf-test-app-1 | sed 's/=.*//'`, ohne Werte. - Warum Stripe eine Anfrage ablehnt, steht im App-Protokoll: `docker logs luf-test-app-1 --tail 300 2>&1 | grep 'Stripe-Anfrage'` (Status, Typ, Parameter und Begründung, keine Schlüssel). **Zurück zum Testweg:** `PAYMENT_DRIVER=test` setzen und neu ausrollen. Offene Stripe-Bestellungen bleiben offen. **Grenzen:** Erstattungen laufen nicht über Stripe. Die Schaltfläche „Widerrufen“ ist im Stripe-Modus ausgeblendet; die Rückzahlung gehört zum Verkaufsstart (Live-Stripe, Belegprozess, Rückabwicklung). Steuer, Rechnung, Rabattcodes und Rechtstexte sind nicht Teil der Sandbox. ## Trennung Test und Prod (beide auf llm-node) | | Test | Prod | |---|---|---| | Branch | `develop` | `main` | | Compose-Projekt | `luf-test` | `luf-prod` | | Deploy-Verzeichnis | `/home/llmadmin/docker/luf-test` | `/home/llmadmin/docker/luf-prod` | | Env-Datei | `/etc/luf/test.env` | `/etc/luf/prod.env` | | Web-Port | 3011/tcp | 3010/tcp | | Volumes, Netz, DB | eigene (Projekt-Präfix) | eigene (Projekt-Präfix) | Ports aus der Momentaufnahme vom 2026-11-15 (frei laut `ss` und `docker ps`). Das Skript bricht ab, wenn der Port von einem fremden Dienst belegt ist. DB, PHP-FPM, Queue und Scheduler veröffentlichen keine Host-Ports. ## Medien-Ablage auf dem NAS | | Test | Prod | |---|---|---| | NAS-Ordner [?] | `/volume1/luf_media_dev` | `/volume1/luf_media` | | Mountpunkt auf llm-node | `/srv/luf/test/media` | `/srv/luf/prod/media` | Der Pfad auf dem NAS ist aus den Ordnernamen abgeleitet und **nicht verifiziert**: Beide Ordner standen am 2026-11-15 nicht in der NFS-Exportliste des NAS (`showmount -e`). Aufbau je Umgebung, nach `03_Zielarchitektur.md` (Zeilen 241/242) und `08_Medien_Streaming_Kennzeichnung.md` (Abschnitt 1): | Ordner | `queue` (Hintergrundverarbeitung) | `app` (Web-Prozess) | |---|---|---| | `originals/` | lesen und schreiben | **kein Zugriff** (nicht gemountet) | | `derived/` (privat) | lesen und schreiben | nur lesen | | `public/` | lesen und schreiben | nur lesen | - Die Trennung geschieht über getrennte Bind-Mounts im Compose. Das NAS selbst unterscheidet nicht zwischen den Containern. - Bind-Mounts mit `create_host_path: false`: Fehlt der NFS-Mount, startet der Container nicht, statt Medien auf die lokale Platte zu schreiben (wie bei Shinkan). - Der Host-Pfad ist in `scripts/deploy.sh` fest an die Umgebung gebunden (`/srv/luf/$LUF_ENV/media`). Test kann nicht auf den Prod-Bestand zeigen. Das Skript prüft vor dem Build, dass der Pfad ein NFS-Mount ist, legt fehlende Unterordner an und macht nach dem Build eine Schreibprobe als `www-data`. - Im Container ist der Pfad derselbe wie auf dem Host. Compose hängt die Unterordner an genau diese Stelle und setzt `MEDIA_PUBLIC_PATH`, `MEDIA_DERIVED_PATH` und `MEDIA_ORIGINALS_PATH` darauf. Ein abweichender Wert in der Env-Datei wird damit überstimmt. - Die CI-Tests mounten keine Medien (`Storage::fake()`). - Datensicherung: Originale sind laut `11_Betrieb_Sicherheit_Datenschutz.md` kritisch (NAS und außer Haus). Snapshots und Replikation für `luf_media` sind Sache des NAS und noch nicht eingerichtet. ## Kanonische Adresse und Weiterleitungen (Nginx im Shop-Container) Die Shop-Adresse ist `https://lara-und-felix.de`. Der Nginx des Containers (`docker/nginx/default.conf`) leitet normale Seitenaufrufe (`GET`, `HEAD`) mit `301` auf diese feste Adresse um, Pfad und Query-String bleiben erhalten. Die Entscheidung trifft eine `map` über Methode, `X-Forwarded-Proto`, öffentlichen Host und Pfad. | Aufruf (Methode `GET`/`HEAD`) | Verhalten | |---|---| | `http://lara-und-felix.de` (nur bei `X-Forwarded-Proto: http`) | `301` auf `https://lara-und-felix.de` | | `http://` und `https://www.lara-und-felix.de` | `301` direkt auf `https://lara-und-felix.de` | | `http://` und `https://www.laraundfelix.de` | `301` direkt auf `https://lara-und-felix.de` | | `https://lara-und-felix.de` | Shop | | `dev.laraundfelix.de` | Testinstanz, unverändert | | `laraundfelix.de` ohne `www` | nicht betroffen, die STRATO-Weiterleitung übernimmt | | Jede andere Methode (`POST`, `PUT`, `DELETE` …) auf den drei Shop-Hosts, nur bei `X-Forwarded-Proto: http` | `403` im Nginx, die Anfrage erreicht Laravel nicht | - **Öffentlicher Host:** erster Wert von `X-Forwarded-Host`, sonst der `Host`-Header (ohne Port, Groß-/Kleinschreibung egal). Eine Adresse ohne Proxy (`127.0.0.1:3010`, `192.168.2.144:3011`) trifft keine Regel. - **Öffentliches Protokoll:** nur `X-Forwarded-Proto`, nie das lokale Schema. Fehlt der Header, wird `lara-und-felix.de` **nicht** weitergeleitet. Dadurch gibt es keine Schleife, falls ein HTTPS-Aufruf ohne den Header ankäme, und der Health-Check des Deploys (`http://127.0.0.1:$WEB_PORT/up`) bleibt unberührt. Die `www`-Adressen werden unabhängig vom Protokoll weitergeleitet. - **Andere Methoden:** Auf `lara-und-felix.de`, `www.lara-und-felix.de` und `www.laraundfelix.de` endet jede Methode außer `GET`/`HEAD` mit `403` im Nginx, **wenn** der Proxy ausdrücklich `X-Forwarded-Proto: http` setzt (erster Wert der Liste). Ein `301` wäre für sie falsch, und über unverschlüsseltes HTTP sollen keine Eingaben ankommen. Unverändert an die Anwendung gehen: alle Methoden über HTTPS (der Stripe-Webhook `/stripe/webhook` ist ein `POST` und muss als `https://` in Stripe eingetragen sein), alle Methoden ohne `X-Forwarded-Proto` (direkter Zugriff, Health-Check) und `dev.laraundfelix.de`. Im Repository ist keine Webhook-Adresse hinterlegt; welche Adresse im Stripe-Dashboard steht, ist [?] nicht geprüft. **Vor dem Aktivieren der HTTP-Regeln prüfen:** Steht dort `http://…`, würde der Webhook mit `403` abgewiesen und muss auf `https://` umgestellt werden. - **ACME:** `/.well-known/acme-challenge/` wird nie umgeleitet oder gesperrt, für jede Methode (Ausnahme zuerst in der `map`), auch nicht auf den `www`-Hosts. Der Shop beantwortet diesen Pfad selbst nicht (Laravel liefert 404); das Zertifikat holt die Synology, sie muss die Prüfung also selbst beantworten und darf sie nicht an den Shop weiterreichen. [?] Beim ersten Erneuern beobachten. - **Signierte URLs:** `App\Http\SignedLink` signiert nur den Pfad (relative Signatur), der Host fließt nicht ein. Ein Wechsel zwischen den Alias-Hosts macht Links also nicht ungültig. Im Repository kommt kein Alias-Host vor; Stripe-Rücksprungadressen entstehen aus `route()` und damit aus `APP_URL` bzw. dem Anfrage-Host. - **Synology:** Setzt der Reverse-Proxy `X-Forwarded-Proto` nicht von selbst, dann einen eigenen Kopfzeilen-Eintrag `X-Forwarded-Proto` mit dem Wert `$scheme` anlegen. Für die Testinstanz ist belegt, dass Protokoll und Host der Synology in der Anwendung ankommen (Stand 2026-11-22: `https://dev.laraundfelix.de/verwaltung` leitet auf `https://dev.laraundfelix.de/verwaltung/login`). Für die Prod-Regeln ist das [?] nicht geprüft. - **Prüfung:** Die Fälle der Tabelle, `HEAD`, Pfad mit Query, Großschreibung, Port im Host, `X-Forwarded-Host`, `POST`/`PUT`, direkter Zugriff und ACME wurden 2026-11-22 mit Windows-nginx 1.27.5 (nicht das Alpine-Image) und `php-cgi` als Upstream durchgespielt (30 Fälle). Reihenfolge und Zusagen der Konfiguration sichert `tests/Unit/NginxConfigTest.php`. - **Nach dem Deploy auf Test** (Lars oder Claude, nur gegen `192.168.2.144:3011`, nie gegen Prod): `curl -sI -H 'Host: www.laraundfelix.de' -H 'X-Forwarded-Proto: https' 'http://192.168.2.144:3011/a?b=1'` muss `301` mit `Location: https://lara-und-felix.de/a?b=1` liefern. ## Einmalig auf llm-node vorzubereiten (nicht automatisiert, braucht `sudo`) 1. `sudo mkdir -p /etc/luf && sudo chown llmadmin:llmadmin /etc/luf && sudo chmod 750 /etc/luf` 2. `/etc/luf/test.env` und `/etc/luf/prod.env` aus [deploy/luf.env.example](../../deploy/luf.env.example) anlegen, `chmod 640`. Je eigener `APP_KEY` (`php artisan key:generate --show`) und eigenes DB-Passwort. Prod: `APP_ENV=production`, `APP_DEBUG=false`. 3. Auf dem Synology zwei Proxy-Einträge: Prod nach `192.168.2.144:3010`, Test nach `192.168.2.144:3011`. 4. In Gitea: Branch-Schutz für `main` (nur Pull Request, Freigabe nötig) und `develop`. Repository-Sichtbarkeit prüfen (siehe unten). 5. Backup (`borgmatic`) wieder grün, bevor produktiv deployt wird. ## Annahmen und offene Punkte - **Repository-Zugriff der Runner [?]:** Die Workflows klonen `http://192.168.2.144:3000/Lars/laraundfelix.git` ohne Zugangsdaten, wie Shinkan. Ist das Repository privat und der Runner nicht angemeldet, schlägt der Clone fehl. - **Gitea-Actions-Syntax [?]:** `needs:` und `github.sha` sind Standard, wurden aber auf dieser Gitea-Version nicht ausprobiert. `actions/checkout` wird bewusst nicht benutzt. - **Laravel-Gerüst:** `composer.json`, `composer.lock`, `package.json` und `package-lock.json` liegen im Root. Die Health-Route ist `/up`. Das Image veröffentlicht die Filament-Assets beim Bau (`php artisan filament:assets`) und baut das Frontend mit `npm run build`. - **Zeilenenden:** `.gitattributes` erzwingt LF für Skripte, weil lokal `core.autocrlf=true` gesetzt ist. - **Öffentliche CMS-Bilder:** Der Web-Prozess schreibt nicht nach `public/`. Ein Upload liegt zuerst auf dem beschreibbaren Storage-Volume (`cms_incoming`). Die Queue kopiert nach `public/` auf dem Medienpfad. Ausgeliefert wird die Datei über die Anwendung unter `/medien/…`, zuerst aus dem öffentlichen Medienpfad, ersatzweise aus dem Eingang. `storage:link` wird dafür nicht gebraucht. - **Reverse Proxy:** Die Anwendung vertraut weitergeleiteten Proxy-Kopfzeilen. Nginx reicht `X-Forwarded-Proto`, `X-Forwarded-Host`, `X-Forwarded-Port` und `X-Forwarded-For` an PHP weiter. Der Proxy vor dem Container muss `X-Forwarded-Proto` setzen, damit Adressen `https` bleiben. - **Upload:** Filme bis 2 GB. Dieselbe Grenze gilt in Livewire (Zwischendatei, sonst 12 MB), im Formular, in PHP (`upload_max_filesize`, `post_max_size`) und in Nginx (`client_max_body_size`). Die signierte Upload-Adresse gilt 60 Minuten. Die Queue kopiert die Datei als Strom nach `derived/` und behält den Auftrag bis zu einer Stunde; `retry_after` der Datenbank-Queue liegt darüber. - **Queue:** Datenbank-Queue (`QUEUE_CONNECTION=database`), kein Redis. Reicht für den Start. Der Worker erlaubt einem Auftrag bis zu einer Stunde (`--timeout=3600`). Das App-Image enthält `ffmpeg`. Die Queue leitet daraus Vorschaubilder und, wenn die Datei lesbar ist, drei HLS-Qualitätsstufen nach `derived/` ab. Fehlt die Ableitung, bleibt die gespeicherte Datei über den bisherigen berechtigten Abruf lesbar. Der Web-Prozess schreibt diese Ableitungen nicht. - **Gate vor Prod:** Merge-Schutz ist eine Gitea-Einstellung und gehört nicht in die Workflows. - **Umzug Test auf den Pi:** Werte oben in `deploy-test.yml` ändern (Label `ubuntu-latest`, Guard auf `raspberrypi5`/`aarch64`, Pfade, Port). Das Dockerfile baut auch für ARM64. Vorher Speicherlage auf dem Pi klären.