Files
laraundfelix/docs/betrieb/DEPLOYMENT.md
T
LarsandClaude Sonnet 5.5 69a22deb1f
CI Feature / test (push) Successful in 2m52s
Deploy Test / test (push) Successful in 2m40s
Deploy Test / deploy (push) Successful in 40s
Sichere Rechnungs- und Livepfad ab und dokumentiere die Entscheidungen zum Verkaufsstart
Eine Bestellung auf Rechnung lässt sich auch mit dem Stripe-Treiber nicht per Karte
bezahlen; der Betreiber, der den Zahlungseingang bestätigt, wird an der Zahlung
festgehalten; im Livebetrieb ist der alte Einzelkauf ohne Pflichtangaben gesperrt und
placeFromCart verlangt die Zustimmungen. ADR-47, Domänenmodell, Lizenzlogik,
Kernabläufe, Szenarien, Fachanforderungen und DEPLOYMENT nachgeführt.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-22 20:11:24 +01:00

20 KiB
Raw Blame History

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 (/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 <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):

  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 (Stand Etappe 1; die Erstattung ist seit dem Verkaufsstart-Stand vorbereitet, siehe „Verkaufsstart: Freigabe und Betrieb“): Erstattungen liefen 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 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.

Verkaufsstart: Freigabe und Betrieb (Stand 24.11.2026, vorbereitet, nicht freigegeben)

Die Produktivfreigabe liegt bei Lars. Der Code enthält sie nicht; er erlaubt sie nur, wenn alle Bedingungen erfüllt sind (App\Domain\Commerce\Shop::live()):

Bedingung Wo gesetzt
SHOP_LIVE_RELEASE=true /etc/luf/prod.env (Standard: aus; nie im Repository)
PAYMENT_DRIVER=stripe /etc/luf/prod.env
STRIPE_SECRET=sk_live_… (Live-Schlüssel; in Produktion sind Testschlüssel nie live, außerhalb der Produktion sind Live-Schlüssel verboten) /etc/luf/prod.env
STRIPE_WEBHOOK_SECRET des Live-Endpunkts, Adresse https://lara-und-felix.de/stripe/webhook (Ereignisse mindestens checkout.session.completed, checkout.session.expired, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed) /etc/luf/prod.env, Stripe-Dashboard
Veröffentlichte CMS-Seiten /agb, /lizenzbedingungen, /widerruf, /impressum, /datenschutz Webpräsenz (Redaktion, Text von der Rechtsberatung)

Weitere Einstellungen: SHOP_INVOICE (Standard an: Kauf auf Rechnung für Organisationen), SHOP_PRICE_NOTE (Preis- und Steuerhinweis im Warenkorb, Standard „Alle Preise in Euro.“), STRIPE_TAX_RATE_ID (im Preis enthaltener Steuersatz; Steuerstatus offen, OPEN-06). Die Verwaltungsseite Verkauf → Verkaufsstart zeigt den Zustand ohne Schlüssel.

  • Erstattung bei Stripe: Checkout::refund ruft vor dem Entzug der Rechte POST /v1/refunds (Vollbetrag, Idempotenzschlüssel luf-refund-<Bestellung>-<Zahlung>) auf; schlägt das fehl, bleibt die Bestellung unverändert. Dafür muss der API-Schlüssel das Recht „Refunds: write“ haben (bei eingeschränktem Schlüssel rk_… prüfen). Die Zahlungsabsicht (payment_intent) wird aus der signierten Meldung gespeichert, sonst bei Stripe abgefragt.
  • Rechnungsweg: Vereine bestellen „auf Rechnung“; der Betreiber erstellt die Rechnung manuell und bestätigt den Zahlungseingang unter Verkauf → Bestellungen.
  • Migration 2026_11_24_100000_add_discounts_licence_scope_and_sales_start: rein ergänzend (neue Tabellen discount_codes, discount_code_targets, discount_code_releases; neue Spalten an offers, offer_versions, orders, order_lines, payments). Nichts wird gelöscht oder umbenannt.
  • Rollback: setzt nur den Code zurück. Der frühere Code kennt Rabatt und Rechnungsweg nicht; vorher offene Bestellungen mit Rabatt oder Zahlungsweg „Rechnung“ stornieren oder abwickeln.
  • Was vor der Freigabe fehlt (Lars bzw. Rechtsberatung): finale Texte (AGB, Lizenzbedingungen je Zweck, Widerrufsbelehrung samt Muster-Widerrufsformular, Impressum, Datenschutzerklärung), Prüfung des Wortlauts der Zustimmungen im Checkout (Entwurf 2026-11-24-entwurf), Steuerstatus und Belegangaben (OPEN-06, E-11: Rechnungsvorlage mit Pflichtangaben, Rechnungsnummernkreis, Steuerausweis), Live-Stripe-Konto mit Webhook, Aufbewahrungsfristen (E-16), Auftragsverarbeitung mit Stripe, ein gesondert beauftragter Sicherheitstest (16, Abschnitt 6.3).