Provider Readiness Runbook¶

Stand: 2026-04-15
Gilt fuer: staging, Go-Live-Vorbereitung von targetshot mit Postmark, Mail-DNS, Stripe und Keygen

Dieses Runbook beschreibt, wie die produktionsrelevanten Fremdprovider vor einem echten Go-Live gegen den erwarteten Scope verifiziert werden.

Ziel¶

Vor dem Go-Live sollen vier Dinge nicht nur konfiguriert, sondern belegbar geprueft sein:

Postmark fuer Verify-Mail, Einladungen und Reports
SPF, DKIM und DMARC fuer die echten Sender-Domains
Stripe fuer Checkout, Billing-Portal und Lifecycle-Reconcile
Keygen fuer Policy, Lizenzvalidierung und Fehlersignale

Die Checks laufen ueber zwei Wege:

Backend-Skript fuer direkte Ops-/CLI-Smoketests
interne Admin-API fuer den Betriebszuschnitt des admin-portal

Verfuegbare Endpunkte und Befehle¶

Admin-API¶

GET /api/admin/providers/readiness Liefert den aktuellen Readiness-Snapshot inklusive letzter persistierter Smoke-Ergebnisse.
POST /api/admin/providers/smoke Fuehrt Smoke-Checks fuer einen Provider oder die gesamte Suite aus und persistiert das Ergebnis standardmaessig.

Beispiel:

curl -sS \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  http://127.0.0.1:8080/api/admin/providers/smoke \
  -d '{
    "provider": "all",
    "targetEmail": "[email protected]",
    "domain": "targetshot.app",
    "dkimSelectors": ["pm-bounces", "pm-reports"],
    "stripeExpectedMode": "test"
  }'

Backend-Skript¶

npm --prefix backend run ops:provider-smoke -- --provider all --target-email [email protected] --domain targetshot.app --dkim-selectors pm-bounces,pm-reports --stripe-expected-mode test

Nuetzliche Flags:

--provider all|postmark|mail_dns|stripe|keygen
--target-email <mail> fuer Postmark-Smoke
--domain <domain> fuer SPF/DMARC
--dkim-selectors <selector1,selector2>
--stripe-expected-mode test|live|any
--keygen-license-key <license>
--no-persist fuer Dry-Run ohne Speicherung

Mail / Postmark¶

Erwartete Variablen¶

POSTMARK_TOKEN
POSTMARK_FROM
POSTMARK_MESSAGE_STREAM
POSTMARK_REPORTS_FROM
optional POSTMARK_SMOKE_TO
optional POSTMARK_DKIM_SELECTORS

Smoke-Ziel¶

Der Smoke deckt bewusst beide produktiven Mail-Pfade ab:

Verify-Mail / Einladungen ueber den transaktionalen Sender
Reports ueber den Reports-Sender inklusive Anhang

Abnahme¶

transaktionale Mail kommt beim Zielkonto an
Report-Mail kommt beim Zielkonto an
Report-Mail enthaelt Anhang
Absender, Reply-/From-Domain und Branding passen zum Zielzustand

Typische Fehlerbilder¶

falscher Sender oder Message Stream
Reports-Sender nicht verifiziert
Mail kommt an, landet aber im Spam wegen DNS-Drift
Attachment- oder HTML-Pfad bricht nur beim Reportversand

Mail-DNS¶

Erwartete DNS-Signale¶

SPF auf der produktiven Sender-Domain
DMARC auf _dmarc.<domain>
DKIM fuer die konfigurierten Selector-Namen

Abnahme¶

SPF vorhanden
DMARC vorhanden
alle erwarteten DKIM-Selectoren liefern TXT oder CNAME

Empfehlung fuer Ops¶

POSTMARK_DKIM_SELECTORS immer explizit im Betriebsvertrag halten
bei Domainwechsel nicht nur Sender aendern, sondern DNS-Smoke erneut fahren
DMARC-Policy und Rueckmeldeadresse mit dokumentieren, nicht nur den TXT-Eintrag selbst

Stripe¶

Erwartete Variablen¶

STRIPE_SECRET_KEY
STRIPE_WEBHOOK_SECRET
TS_CLUB_BILLING_STRIPE_PRICE_ID_MONTHLY
TS_CLUB_BILLING_STRIPE_PRICE_ID_YEARLY

Automatischer Smoke¶

Der technische Smoke prueft:

Stripe-API ist erreichbar
Account ist lesbar
Monthly- und Yearly-Price existieren
Prices sind aktiv
livemode passt optional zum erwarteten Scope (test oder live)

Manuelle Go-Live-Abnahme¶

Diese Punkte bleiben bewusst im echten Lifecycle-Test:

Checkout mit echtem Club erfolgreich durchlaufen
Rueckleitung in club-billing pruefen
Webhook-Zustellung im echten Endpoint verifizieren
Stripe synchronisieren pruefen
Abo kuendigen pruefen
Kuendigung zuruecknehmen pruefen
past_due oder fehlgeschlagene Zahlung im Support-Fall nachvollziehen

Das fachliche Billing-Recovery bleibt im Club Billing Runbook beschrieben; dieses Dokument deckt den Provider-Readiness-Aspekt davor ab.

Keygen¶

Erwartete Variablen¶

TS_CLUB_LICENSE_KEYGEN_ACCOUNT
TS_CLUB_LICENSE_KEYGEN_API_TOKEN
TS_CLUB_LICENSE_KEYGEN_POLICY_ID
optional TS_CLUB_LICENSE_KEYGEN_POLICY_NAME

Automatischer Smoke¶

Der technische Smoke prueft:

Keygen-API ist erreichbar
konfigurierte Policy ist lesbar
Policy-ID passt
optional: eine angegebene Lizenz kann validiert werden

Manuelle Go-Live-Abnahme¶

Club-Lizenz wird nach erfolgreichem Checkout provisioniert
ungueltige oder gesperrte Lizenz liefert das erwartete Fehlerbild
Admin-/Club-Sicht zeigt denselben Providerzustand wie Keygen

Secret-Rotation und Verantwortlichkeiten¶

Bereich	Secrets / Konfiguration	Verantwortlich	Rotation / Ereignis
Postmark	`POSTMARK_TOKEN`, Sender, Stream	Plattformbetrieb	bei Leak, Teamwechsel oder Sender-/Server-Wechsel
Mail-DNS	SPF, DKIM, DMARC, `POSTMARK_DKIM_SELECTORS`	Plattformbetrieb + DNS-Verantwortliche	bei Domainwechsel, Providerwechsel, DKIM-Neuausstellung
Stripe	`STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, Price IDs	Plattformbetrieb	bei Leak, Scope-Wechsel `test`/`live`, Preis-Neuschnitt
Keygen	Account, API-Token, Policy-ID/-Name	Plattformbetrieb	bei Leak, Policy-Wechsel, Token-Ablauf

Mindestvertrag¶

Secrets liegen nicht nur in lokalen .env-Dateien, sondern auch in der zentralen Betriebsdoku bzw. Secret-Verwaltung
Owner und Rotation-Trigger sind benannt
nach jeder Rotation wird mindestens der passende technische Smoke erneut gefahren

Go-Live-Abschluss fuer Punkt 65¶

Punkt 65 ist erst dann wirklich abgenommen, wenn:

fuer alle aktiven Provider ein aktueller Smoke-Lauf dokumentiert ist
Billing und Licensing entweder mit echtem Scope getestet oder explizit aus dem ersten Go-Live ausgeschlossen wurden
Secret-Owner, Rotation und DNS-Vertrag nicht nur implizit bekannt, sondern dokumentiert sind