Dies ist Teil 2 meiner Serie zur headless WordPress-Migration. Headless WordPress deployment ist der Moment, in dem die echten Probleme beginnen, weil DNS, SSL, Bilder, Formulare und Redirects auf unterschiedliche Weise kaputtgehen. In Teil 1 habe ich das Frontend an einem Tag mit Claude Code, Stitch MCP und Next.js neu aufgebaut. In diesem Artikel zeige ich die Deployment-Probleme, auf die ich gestoßen bin, wie ich sie gelöst habe, und warum AI trotzdem menschliches Urteilsvermögen brauchte.
Das Headless-WordPress-Deployment-Problem, über das niemand spricht
Der Aufbau des Frontends ist der einfache Teil. In meiner Erfahrung wird headless WordPress deployment dann schwierig, sobald du eine Website in zwei Systeme aufteilst: Vercel für das Frontend und WordPress für das Backend. Du hast dann keinen einfachen Stack mehr. Du hast DNS, Zertifikate, Media-URLs, REST-Endpunkte und Admin-Zugriff, die alle in unterschiedliche Richtungen ziehen.
Als `optagonen.se` zu Vercel wechselte, landete jede Anfrage, die vorher WordPress traf, stattdessen im neuen Frontend. Das hat GraphQL, Uploads, Contact Form 7 und den Admin-Zugriff in einem Schlag kaputtgemacht. Wenn du ein eigenes headless WordPress deployment planst, musst du für diese Breakpoints entwerfen, bevor du DNS umstellst.
Ich habe das in einer echten Production-Migration getestet, nicht in einer Sandbox. Die Erkenntnis war klar: Der Code war schnell fertig, aber die Infrastruktur hat Zeit gebraucht.
DNS aufteilen für ein Headless-WordPress-Deployment
Die sauberste Lösung war, WordPress ein eigenes Subdomain zu geben: `wp.optagonen.se`. So konnte ich Frontend und Backend trennen, ohne alles über einen einzigen Origin reverse zu proxyn. Außerdem wurde die Architektur leichter zu durchschauen, wenn man SSL und Media-Delivery debuggt.
| Domain | Points to | Purpose |
|---|---|---|
| --- | --- | --- |
| `optagonen.se` | Vercel | Frontend in Next.js |
| `wp.optagonen.se` | Origin server | WordPress Backend |
Ich habe `wp.optagonen.se` als Alias in Hestia hinzugefügt, den DNS-A-Record auf die Origin-IP gezeigt und die Environment-Variable im Frontend aktualisiert:
Dieser Teil ist auf dem Papier einfach. In der Praxis hat das headless WordPress deployment eine Kettenreaktion ausgelöst. Jedes System, das von der alten Domain ausging, brauchte ein neues Ziel.
Headless WordPress Deployment und SSL-Zertifikatsfehler
Als Erstes ist SSL kaputtgegangen. Das alte Let's-Encrypt-Zertifikat deckte nur `optagonen.se` und `www.optagonen.se` ab, daher schlug `https://wp.optagonen.se` sofort fehl. Das ist erwartetes Verhalten. Let's Encrypt validiert die Domain-Eigentümerschaft pro Hostname, und der Browser lehnt die Verbindung ab, wenn das Zertifikat nicht passt.
Die eingebaute Erneuerung von Hestia ist fehlgeschlagen, weil es immer noch versuchte, die Hauptdomain über HTTP-01 zu validieren, aber die Hauptdomain zeigte jetzt auf Vercel. Certbot ist aus einem anderen Grund fehlgeschlagen: Hestia hat die ACME-Challenge abgefangen und stattdessen seinen eigenen Thumbprint zurückgegeben, statt den von Certbot. Das ist genau die Art von Konflikt, die AI nicht aus ersten Prinzipien ableiten kann. Du musst wissen, wie das Panel sich verhält.
Ich habe es gelöst, indem ich die ACME-Challenge-Konfiguration von Hestia vorübergehend aus dem nginx-include-Pfad verschoben habe, ein Zertifikat nur für `wp.optagonen.se` ausgestellt habe und dann die erneuerten Dateien zurück in das SSL-Verzeichnis von Hestia kopiert habe. Außerdem habe ich einen Renewal-Hook hinzugefügt, damit der Prozess automatisch bleibt.
Für das Vertrauen habe ich mich auf die offiziellen Docs von Let's Encrypt und Certbot gestützt. Das hat geholfen, den ACME-Flow zu bestätigen, bevor ich wieder an Production herumgedreht habe.
Warum das Headless-WordPress-Deployment die Subdomain abgelehnt hat
Sobald SSL funktionierte, hat WordPress den neuen Host trotzdem nicht akzeptiert. Statt GraphQL-Daten zurückzugeben, hat es auf `/wp-signup.php` umgeleitet. Das sagte mir, dass WordPress den eingehenden Host-Header nicht mochte.
Die Lösung war eine einzelne nginx-Direktive:
Diese Zeile hat WordPress so verhalten lassen, als kämen die Requests weiterhin von der Hauptdomain, während der Browser auf `wp.optagonen.se` blieb. In einem headless WordPress deployment ist diese Art von Host-Normalisierung wichtiger, als die meisten erwarten. WordPress ist sehr meinungsstark, was Site-URLs angeht.
Ich habe diese gleiche Klasse von Problem auch bei anderen Migrationen gesehen. Das Frontend funktioniert, das Backend antwortet, und dann bricht ein falsch passender Host-Header den Session-Flow still und leise.
Bilder sind nach dem Headless-WordPress-Deployment kaputtgegangen
Nach dem Deploy hat jedes Bild einen 502-Fehler zurückgegeben. Das lag daran, dass die WordPress-Media-URLs weiterhin auf `/wp-content/uploads/...` zeigten, und diese Pfade sich jetzt gegen Vercel auflösten statt gegen den Origin-Server. In meinem Setup kam das Problem aus zwei Bereichen: hardcodierte URLs in statischen Dateien und dynamische URLs, die von WPGraphQL zurückgegeben wurden.
Ich habe zuerst die hardcodierten URLs gefixt. Ich habe jede Referenz von `https://optagonen.se/wp-content/uploads/` durch `https://wp.optagonen.se/wp-content/uploads/` über sechs Dateien hinweg ersetzt. Das hat etwa 70 Bildpfade abgedeckt.
Dann habe ich die dynamischen GraphQL-URLs mit einem Next.js Rewrite gefixt:
So blieb das Frontend sauber und ich musste keine Media-Daten innerhalb von WordPress umschreiben. Außerdem wurde das headless WordPress deployment besser wartbar, weil der Browser weiterhin denselben Pfad anfragt, während der Server das Proxying übernimmt.
Wenn du tiefer in diese Art von Systemdesign einsteigen willst, empfehle ich, meinen AI-powered WordPress migration workflow→ zu lesen und meine multi-agent content pipeline→. Diese Posts zeigen, wie ich Infrastruktur- und Content-Systeme um Automatisierung herum strukturiere.
Kontaktformulare, IDs und die letzte Deployment-Falle
Contact Form 7 sah zunächst gut aus, aber das Formular hat aufgehört zu funktionieren, weil die ID im Frontend falsch war. Die Standard-Form-ID war `1`, aber das echte Formular in WordPress war `8`. Ein schneller API-Check hat das bestätigt.
Das war ein kleiner Fix, aber er ist wichtig. In einem headless WordPress deployment kann eine einzige falsche ID ein funktionierendes Formular kaputt aussehen lassen, selbst wenn das Backend gesund ist. Ich habe `CF7_FORM_ID=8` gesetzt, und das Formular war sofort wieder online.
Darum teste ich immer den kompletten Flow manuell:
Diese Reihenfolge findet Probleme schneller als nur anhand von Logs zu raten.
Wobei AI geholfen hat und was es verpasst hat
Claude Code hat mir geholfen, schnell voranzukommen, aber es hat das Verstehen nicht ersetzt. Es hat die repetitiven Teile gut erledigt: Konfigurationsdateien durchsuchen, nginx-Snippets generieren, bei certbot-Kommandos helfen und Bild-URLs im Bulk ersetzen. Außerdem hat es die Fehlerkette im Gedächtnis behalten, was Zeit gespart hat, wenn ein Fix ein anderes Problem erzeugt hat.
Allerdings konnte AI nicht die komplette Architektur entscheiden. Es wusste nicht, dass Hestia ACME-Requests abfängt. Es wusste nicht, wann man eine Subdomain statt eines reverse proxies verwenden sollte. Und es wusste nicht die Reihenfolge der Operationen, die einen Downtime-freien Ablauf ermöglicht.
Der echte Wert von AI in einem headless WordPress deployment ist: Es beschleunigt die Diagnose, aber du brauchst trotzdem den Menschen, der den Stack versteht. Ich nutze denselben Grundsatz in meiner Arbeit beim Aufbau von AI automation systems for e-commerce→ und in meiner Content-Pipeline-Arbeit.
Finale Architektur nach dem Deployment
Nach den Fixes hat sich der Stack in eine saubere Trennung eingependelt:
| Component | Location | Purpose |
|---|---|---|
| --- | --- | --- |
| Next.js Frontend | Vercel | Stellt Pages bereit und übernimmt Routing |
| WordPress + WPGraphQL | `wp.optagonen.se` | Content API und Media Storage |
| Contact Form 7 | `wp.optagonen.se` | Form Handling |
| Image Proxy | Next.js Rewrite-Regel | Leitet Uploads zum Origin |
| Frontend SSL | Vercel | Automatisches Management |
| Backend SSL | Certbot + Renewal-Hook | Automatisch erneuerte Zertifikate |
Diese Struktur ist stabil und lässt sich leicht debuggen. Außerdem bleibt das Frontend schnell, während der redaktionelle Workflow in WordPress erhalten bleibt. Bei einem headless WordPress deployment ist genau dieses Gleichgewicht das Ziel.
Lessons aus diesem Headless-WordPress-Deployment
Das habe ich aus der Migration gelernt:
Diese Lessons stammen aus einer echten Production-Umstellung, nicht aus einem Tutorial. Deshalb plane ich heute genauso viel Zeit für Deployment ein wie fürs Bauen.
Fazit
Headless WordPress deployment ist nicht schwer wegen des Codes. Es ist schwer, weil DNS, SSL, Media und Host-Header alle voneinander abhängen. In dieser Migration habe ich die Subdomain-Trennung, die Zertifikatsvalidierung, die Bildauslieferung und Contact Form 7 gefixt, und ich habe genau gelernt, wo AI hilft und wo es aufhört.
Wenn du deine eigene Migration planst, lies zuerst den Frontend-Neubau, teste früh deinen Zertifikats-Flow und verifiziere jeden Media-Pfad vor dem Launch. Danach prüfe die Live-Site, bestätige die Formulare und stelle sicher, dass sich das Backend weiterhin so verhält, wie WordPress es erwartet.
Wenn du mehr praktische Deployment-Aufschlüsselungen willst, lies die verwandten Posts weiter und vergleiche sie mit deinem eigenen Stack. Das ist der schnellste Weg, um Fehler in deinem nächsten headless WordPress deployment zu vermeiden.
Vorgeschlagener Bild-Alt-Text: