Bestellung 7 wurde über die Stripe-Kasse im Testmodus bezahlt und per Webhook freigeschaltet. Betriebsdoku um die erlebten Stolpersteine ergänzt (pk_ statt sk_, Managed Payments, inklusiver Steuersatz, Neuausrollen, Fehlersuche im Protokoll). Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
13 KiB
LUF – Deployment (Stand 2026-11-15)
Abgeleitet aus dem Shinkan-Verfahren, siehe 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 (/upund Datenbankzugriff). Bei Fehler Rollback auf den letzten erfolgreichen Image-Tag (.last_good_tag). Der Deploy legt keinen Demokatalog an.DemoCatalogSeederbleibt 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)
/etc/luf/prod.envbzw./etc/luf/test.envauf llm-node bearbeiten (Besitzerllmadmin, Rechte640).- 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.
- Prüfen:
docker exec luf-prod-app-1 printenv <VARIABLE>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):
-
In Stripe den Testmodus („Sandbox“) wählen. Unter Entwickler > API-Schlüssel den Geheimschlüssel
sk_test_…kopieren. -
Unter Entwickler > Webhooks einen Endpunkt anlegen: URL
https://dev.laraundfelix.de/stripe/webhook, Ereignissecheckout.session.completed,checkout.session.expired,checkout.session.async_payment_succeeded,checkout.session.async_payment_failed. Das Signiergeheimniswhsec_…des Endpunkts kopieren. -
Auf llm-node in
/etc/luf/test.enveintragen (Rechte640, 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_IDist 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 alszu_pruefenfestgehalten wird und nichts freischaltet. Welcher Satz gilt, entscheiden Steuer und Finance, nicht die Anwendung. -
In Gitea den letzten Lauf von „Deploy Test“ erneut starten (siehe „Env-Datei ändern“).
docker exec luf-test-app-1 printenv PAYMENT_DRIVERmussstripezeigen. -
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_SECRETmuss der geheime Schlüsselsk_test_…sein, nicht der veröffentlichbarepk_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_IDmuss 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.envwirkt erst nach dem erneuten Lauf „Deploy Test“ (siehe oben). Die Variablennamen im Container zeigtdocker 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.shfest 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 alswww-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_PATHundMEDIA_ORIGINALS_PATHdarauf. 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.mdkritisch (NAS und außer Haus). Snapshots und Replikation fürluf_mediasind Sache des NAS und noch nicht eingerichtet.
Einmalig auf llm-node vorzubereiten (nicht automatisiert, braucht sudo)
sudo mkdir -p /etc/luf && sudo chown llmadmin:llmadmin /etc/luf && sudo chmod 750 /etc/luf/etc/luf/test.envund/etc/luf/prod.envaus deploy/luf.env.example anlegen,chmod 640. Je eigenerAPP_KEY(php artisan key:generate --show) und eigenes DB-Passwort. Prod:APP_ENV=production,APP_DEBUG=false.- Auf dem Synology zwei Proxy-Einträge: Prod nach
192.168.2.144:3010, Test nach192.168.2.144:3011. - In Gitea: Branch-Schutz für
main(nur Pull Request, Freigabe nötig) unddevelop. Repository-Sichtbarkeit prüfen (siehe unten). - 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.gitohne Zugangsdaten, wie Shinkan. Ist das Repository privat und der Runner nicht angemeldet, schlägt der Clone fehl. - Gitea-Actions-Syntax [?]:
needs:undgithub.shasind Standard, wurden aber auf dieser Gitea-Version nicht ausprobiert.actions/checkoutwird bewusst nicht benutzt. - Laravel-Gerüst:
composer.json,composer.lock,package.jsonundpackage-lock.jsonliegen im Root. Die Health-Route ist/up. Das Image veröffentlicht die Filament-Assets beim Bau (php artisan filament:assets) und baut das Frontend mitnpm run build. - Zeilenenden:
.gitattributeserzwingt LF für Skripte, weil lokalcore.autocrlf=truegesetzt 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 nachpublic/auf dem Medienpfad. Ausgeliefert wird die Datei über die Anwendung unter/medien/…, zuerst aus dem öffentlichen Medienpfad, ersatzweise aus dem Eingang.storage:linkwird dafür nicht gebraucht. - Reverse Proxy: Die Anwendung vertraut weitergeleiteten Proxy-Kopfzeilen. Nginx reicht
X-Forwarded-Proto,X-Forwarded-Host,X-Forwarded-PortundX-Forwarded-Foran PHP weiter. Der Proxy vor dem Container mussX-Forwarded-Protosetzen, damit Adressenhttpsbleiben. - 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 nachderived/und behält den Auftrag bis zu einer Stunde;retry_afterder 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ältffmpeg. Die Queue leitet daraus Vorschaubilder und, wenn die Datei lesbar ist, drei HLS-Qualitätsstufen nachderived/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 (Labelubuntu-latest, Guard aufraspberrypi5/aarch64, Pfade, Port). Das Dockerfile baut auch für ARM64. Vorher Speicherlage auf dem Pi klären.