Bu, headless WordPress geçiş seriminin 2. bölümü. Headless WordPress deployment (headless WordPress dağıtımı) işte asıl sorunların başladığı yerdir; çünkü DNS, SSL, görseller, formlar ve yönlendirmeler farklı şekillerde bozulur. 1. Bölüm’de Claude Code, Stitch MCP ve Next.js ile ön yüzü tek günde yeniden kurdum. Bu yazıda, karşılaştığım dağıtım sorunlarını, nasıl çözdüğümü ve neden AI’nin hâlâ insan muhakemesine ihtiyaç duyduğunu anlatıyorum.
The Headless WordPress Deployment Problem Nobody Talks About
Ön yüzü kurmak kolay kısım. Benim deneyimimde, headless WordPress deployment tek bir siteyi iki sisteme böldüğünüz anda zorlaşır: ön yüz için Vercel ve arka uç için WordPress. Artık tek bir basit yığınınız yok. DNS, sertifikalar, medya URL’leri, REST endpoint’leri ve yönetici erişimi farklı yönlere çekiyor.
`optagonen.se` Vercel’e taşındığında, daha önce WordPress’e giden her istek yeni ön yüze düşmeye başladı. Bu, GraphQL’i, yüklemeleri, Contact Form 7’yi ve yönetici erişimini tek hamlede bozdu. Kendi headless WordPress deployment planınızı yapıyorsanız, DNS’i değiştirmeden önce bu kırılma noktaları için tasarım yapmanız gerekir.
Bunu gerçek bir üretim geçişinde test ettim; bir sandbox’ta değil. Ders açıktı: kod hızlı bitti, ama altyapı zaman aldı.
Splitting DNS for a Headless WordPress Deployment
En temiz çözüm, WordPress’e kendi alt alan adını vermekti: `wp.optagonen.se`. Bu, her şeyi tek bir origin üzerinden ters proxy yapmaya zorlamadan ön yüz ile arka ucu ayırdı. Ayrıca SSL ve medya teslimini sorun giderirken mimariyi anlamayı kolaylaştırdı.
| Domain | Points to | Purpose |
|---|---|---|
| --- | --- | --- |
| `optagonen.se` | Vercel | Frontend in Next.js |
| `wp.optagonen.se` | Origin server | WordPress backend |
`wp.optagonen.se`’yi Hestia’da alias olarak ekledim, DNS A kaydını origin IP’ye işaretledim ve ön yüz ortam değişkenini güncelledim:
Bu kâğıt üzerinde basit. Ama pratikte headless WordPress deployment, zincirleme bir reaksiyonu ortaya çıkardı. Eski domain’i varsayan her sistem yeni bir hedefe ihtiyaç duydu.
Headless WordPress Deployment and SSL Certificate Failures
İlk bozulan şey SSL oldu. Eski Let's Encrypt sertifikası yalnızca `optagonen.se` ve `www.optagonen.se`’yi kapsıyordu; bu yüzden `https://wp.optagonen.se` hemen başarısız oldu. Bu beklenen bir davranış. Let's Encrypt, her hostname için alan adı sahipliğini doğrular ve sertifika eşleşmiyorsa tarayıcı bağlantıyı reddeder.
Hestia’nın yerleşik yenileme işlemi başarısız oldu; çünkü hâlâ ana domain’i HTTP-01 üzerinden doğrulamaya çalışıyordu, ama ana domain artık Vercel’e işaret ediyordu. Certbot ise başka bir nedenle başarısız oldu: Hestia ACME challenge’ı yakalayıp Certbot’un parmak izini yerine kendi thumbprint’ini döndürdü. AI’nin bunu ilk prensiplerden çıkaramayacağı türden bir çakışma bu. Panelin nasıl davrandığını bilmeniz gerekir.
Bunu, Hestia’nın ACME challenge konfigürasyonunu geçici olarak nginx include path’inden çıkarıp yalnızca `wp.optagonen.se` için sertifika düzenleyerek ve ardından yenilenen dosyaları Hestia’nın SSL dizinine geri kopyalayarak çözdüm. Sürecin otomatik kalması için bir yenileme hook’u da ekledim.
Güven için Let's Encrypt ve Certbot’ın resmi dokümanlarına yaslandım. Üretime tekrar dokunmadan önce ACME akışını doğrulamaya yardımcı oldu.
Why the Headless WordPress Deployment Rejected the Subdomain
SSL çalıştıktan sonra bile WordPress yeni host’u kabul etmedi. GraphQL verisi döndürmek yerine `/wp-signup.php`’ye yönlendirdi. Bu, WordPress’in gelen host header’ını beğenmediğini gösterdi.
Çözüm tek bir nginx direktifiydi:
Bu satır, istekler hâlâ ana domain’den geliyormuş gibi WordPress’in davranmasını sağladı; tarayıcı ise `wp.optagonen.se` üzerinde kaldı. headless WordPress deployment içinde bu tür host normalizasyonu, insanların beklediğinden daha fazla önem taşır. WordPress, site URL’leri konusunda oldukça görüş sahibidir.
Bu aynı sorun sınıfını başka geçişlerde de gördüm. Ön yüz çalışır, arka uç yanıt verir; sonra eşleşmeyen bir host header oturum akışını sessizce bozar.
Images Broke After the Headless WordPress Deployment
Dağıtımdan sonra her görsel 502 hatası döndürdü. Bunun nedeni WordPress medya URL’lerinin hâlâ `/wp-content/uploads/...` şeklinde işaret etmesiydi ve bu yollar artık origin server yerine Vercel’e göre çözümleniyordu. Kurulumumda sorun iki yerden geldi: statik dosyalardaki hardcoded URL’ler ve WPGraphQL tarafından dönen dinamik URL’ler.
Önce hardcoded URL’leri düzelttim. `https://optagonen.se/wp-content/uploads/` referanslarının her birini, altı dosya boyunca `https://wp.optagonen.se/wp-content/uploads/` ile değiştirdim. Bu, yaklaşık 70 görsel yolunu kapsadı.
Sonra dinamik GraphQL URL’lerini Next.js rewrite ile düzelttim:
Bu, ön yüzü temiz tuttu ve medya verisini WordPress içinde yeniden yazmaktan kaçındı. Ayrıca tarayıcının hâlâ aynı path’i istemesi, sunucunun ise proxy’lemeyi üstlenmesi sayesinde headless WordPress deployment daha sürdürülebilir hale geldi.
Bu tür bir sistem tasarımına daha derin girmek isterseniz, AI-powered WordPress migration workflow→ yazımı ve multi-agent content pipeline→ yazımı okumanızı öneririm. Bu yazılar, otomasyon etrafında altyapı ve içerik sistemlerini nasıl yapılandırdığımı gösteriyor.
Contact Forms, IDs, and the Last Deployment Trap
Contact Form 7 ilk başta düzgün görünüyordu, ama form çalışmayı bıraktı; çünkü ön yüzdeki ID yanlıştı. Varsayılan form ID’si `1`’di, ama WordPress’teki gerçek form `8`’di. Hızlı bir API kontrolü bunu doğruladı.
Bu küçük bir düzeltmeydi, ama önemli. headless WordPress deployment içinde tek bir yanlış ID, arka uç sağlıklı olsa bile çalışan bir formu bozuk gibi gösterebilir. `CF7_FORM_ID=8` ayarladım ve form hemen yeniden çevrimiçi oldu.
Bu yüzden ben her zaman tam akışı manuel test ederim:
Bu sıra, yalnızca loglara bakarak tahmin etmekten daha hızlı sorun yakalar.
What AI Helped With and What It Missed
Claude Code hızlı ilerlememi sağladı, ama anlayışın yerini tutmadı. Tekrarlayan işleri iyi yaptı: config dosyalarında arama yapmak, nginx snippet’leri üretmek, certbot komutlarında yardımcı olmak ve görsel URL’lerini toplu halde değiştirmek. Ayrıca hata zincirini akılda tuttu; bir düzeltme başka bir sorunu doğurduğunda zaman kazandırdı.
Ancak AI tam mimariye karar veremezdi. Hestia’nın ACME isteklerini yakalayacağını bilmiyordu. Reverse proxy yerine ne zaman alt alan adı kullanılacağını bilmiyordu. Ayrıca kesintisizliği önleyecek operasyon sırasını da bilmiyordu.
headless WordPress deployment içinde AI’nin gerçek değeri şudur: teşhisi hızlandırır, ama yine de yığını anlayan insan gerekir. Ben de AI automation systems for e-commerce→ inşa ederken ve içerik pipeline çalışmamda aynı prensibi kullanıyorum.
Final Architecture After the Deployment
Düzeltmelerden sonra yığın temiz bir ayrımda oturdu:
| Component | Location | Purpose |
|---|---|---|
| --- | --- | --- |
| Next.js frontend | Vercel | Sayfaları sunar ve routing’i yönetir |
| WordPress + WPGraphQL | `wp.optagonen.se` | Content API ve medya depolama |
| Contact Form 7 | `wp.optagonen.se` | Form işleme |
| Image proxy | Next.js rewrite rule | Upload’ları origin’e yönlendirir |
| Frontend SSL | Vercel | Otomatik yönetim |
| Backend SSL | Certbot + renewal hook | Otomatik yenilenen sertifikalar |
Bu yapı stabil ve hata ayıklaması kolay. Ayrıca WordPress içindeki editoryal iş akışını korurken ön yüzü hızlı tutar. Bir headless WordPress deployment için hedef budur.
Lessons From This Headless WordPress Deployment
Bu headless WordPress deployment geçişinden öğrendiklerim:
Bu dersler bir tutorial’dan değil, gerçek bir üretim hamlesinden geldi. Bu yüzden artık deployment için, inşa etmek kadar zaman ayırıyorum.
Conclusion
Headless WordPress deployment kod yüzünden zor değil. Zor; çünkü DNS, SSL, medya ve host header’ların hepsi birbirine bağlı. Bu geçişte alt alan adı ayrımını, sertifika doğrulamasını, görsel teslimini ve Contact Form 7’yi düzelttim; ayrıca AI’nin nerede yardımcı olduğunu ve nerede durduğunu tam olarak öğrendim.
Kendi geçişinizi planlıyorsanız, önce frontend yeniden inşasını okuyun, sertifika akışını erken test edin ve yayına almadan önce her medya path’ini doğrulayın. Sonra canlı siteyi kontrol edin, formları doğrulayın ve arka uç tarafının WordPress’in beklediği şekilde hâlâ davrandığından emin olun.
Daha pratik deployment kırılımları istiyorsanız, ilgili yazıları okumaya devam edin ve kendi stack’inizle karşılaştırın. Bir sonraki headless WordPress deployment’ınızda hatalardan kaçınmanın en hızlı yolu bu.
Suggested image alt text: