Deploynix’te Laravel API ve Ayrı Ön Yüz (Next.js, Nuxt, SPA) Dağıtımı

Laravel uygulamalarında Blade şablonları her sayfa için kullanılmaya devam etse de, artık tek seçenek değiller. Daha fazla ekip, Laravel arka uçlarını tamamen bir API olarak oluşturmayı ve bunu Next.js, Nuxt gibi bir JavaScript ön uç çerçevesiyle veya React, Vue veya Svelte kullanarak oluşturulmuş bir tek sayfa uygulamasıyla eşleştirmeyi tercih ediyor. Bu mimari gerçek faydalar sunuyor: uzmanlaşmış ön uç araçları, bağımsız dağıtım döngüleri ve tek bir API üzerinden birden fazla istemciye (web, mobil, üçüncü taraf entegrasyonları) hizmet verme imkanı.

Ancak bu mimari, geleneksel bir Laravel uygulamasında olmayan dağıtım karmaşıklığını da beraberinde getiriyor. Artık dağıtmanız gereken iki uygulama, yönetmeniz gereken iki set ortam değişkeni ve ön uç ile arka uç arasında dikkatli bir şekilde yapılandırılması gereken bir ağ sınırı var. CORS başlıkları, kimlik doğrulama tokenları, API sürümleme ve dağıtım koordinasyonu birincil endişeler haline geliyor.

Bu kılavuzda, bu mimariyi Deploynix üzerinde nasıl kuracağınıza dair adım adım bir rehber sunacağız. Sunucu topolojisi, site yapılandırması, CORS yönetimi, kimlik doğrulama ve uygulamanızın iki yarısını senkronize tutan dağıtım stratejileri hakkında bilgi vereceğiz.

Sunucu Topolojisini Seçme

İlk karar, API’nizin ve ön uç uygulamanızın aynı sunucuda mı yoksa ayrı sunucularda mı olacağıdır. Her iki yaklaşım da Deploynix üzerinde çalışır ve doğru seçim, trafik desenlerinize ve ölçeklendirme ihtiyaçlarınıza bağlıdır.

Aynı Sunucu, Farklı Siteler

Uygulamaların erken aşamalarında, hem Laravel API’sinin hem de ön uç uygulamanın aynı Deploynix App sunucusunu kullanması en basit yaklaşımdır. Aynı sunucuda her biri kendi Git havuzuna ve alan adına işaret eden iki site oluşturursunuz.

Laravel API’niz api.yourapp.com adresinde, standart bir Laravel sitesi olarak PHP işlemesiyle yapılandırılabilir. Ön uç uygulamanız app.yourapp.com adresinde yer alabilir ve statik dosyalar sunmak üzere ya da bir Node.js sürecine (Next.js veya Nuxt ile sunucu tarafı işleme için) proxy olarak yapılandırılabilir.

Bu yaklaşım, ön uç sunucusunun sunucu tarafı işleme katmanı ile API’niz arasındaki ağ gecikmesini en aza indirir. Eğer Next.js uygulamanız sayfa işleme sırasında sunucu tarafı API çağrıları yapıyorsa, bu çağrılar internet üzerinden değil, localhost üzerinden gerçekleşir.

Ayrı Sunucular

Uygulamanız geliştikçe, bu endişeleri ayırmak isteyeceksiniz. Laravel API’niz bir App sunucusunda (veya bir Yük Dengeleyici arkasında birden fazla Web sunucusunda) çalışacakken, ön uç kendine ait bir Web sunucusunda çalışabilir. Bu, bağımsız ölçeklendirme sağlar: Eğer API’yi darboğaz haline getiriyorsanız, ön uç altyapınıza dokunmadan daha fazla API sunucusu ekleyebilirsiniz.

Deploynix üzerinde, bu sunucuları anlamlı olacak şekilde farklı bulut sağlayıcılarında temin edebilirsiniz. API’niz maliyet etkin hesaplama için Hetzner’da çalışırken, ön uç kullanıcılarınıza daha yakın bir sağlayıcıda çalışabilir. Deploynix, SSH bağlantılarını, kaynak tahsisini ve dağıtımları tüm sağlayıcılar arasında aynı arayüzle yönetir.

Özelleşmiş bir Veritabanı sunucusu ve Önbellek sunucusu ise altyapıyı tamamlar. API’niz bu arka uç hizmetlerine bağlanırken, ön uç sunucusunun yalnızca API ile iletişim kurması (ve statik varlıklar için muhtemelen bir CDN ile) yeterlidir.

Laravel API’sini Kurma

Deploynix üzerindeki Laravel API yapılandırmanız, birkaç özel husus ile standart Laravel site kurulumunu takip eder.

API Odaklı Ortam Yapılandırması

API olduğunuzu yansıtmak için .env dosyanızda değişiklikler yapmalısınız. Kimlik doğrulama stratejinize bağlı olarak SESSION_DRIVER‘ı uygun şekilde ayarlayın. Token tabanlı kimlik doğrulama için Laravel Sanctum kullanıyorsanız (ki bu, Deploynix’in de kullandığı bir yöntemdir), API yalnızca istekleri için oturumlara ihtiyacınız olmayabilir. Eğer çerezler ile SPA kimlik doğrulama modunu kullanıyorsanız, oturum desteğine ihtiyacınız olacaktır.

SANCTUM_STATEFUL_DOMAINS değişkeninizi ön uç alanınızı içerecek şekilde ayarlayın. Bu, Sanctum’a ön uçtan gelen isteklerin birinci taraf olarak ele alınmasını ve gerekli olduğunda çerez tabanlı kimlik doğrulamanın kullanılmasını söyler:

SANCTUM_STATEFUL_DOMAINS=app.yourapp.com,localhost:3000
    

localhost:3000 eklemek, ön uç geliştiricilerinizin yerel gelişim sırasında üretim veya test API’si ile kimlik doğrulama yapmasına olanak tanır.

CORS Yapılandırması

Çapraz Kaynak Paylaşımı, app.yourapp.com ön uç uygulamanızın api.yourapp.com API’sine istek yapmasını sağlayan mekanizmadır. Laravel, kutudan çıkar çıkmaz CORS ara yazılımı içerir ve doğru yapılandırmak kritik önem taşır.

config/cors.php dosyanızda, izin verilen kaynakları ön uç alanınızı içerecek şekilde yapılandırın. Üretimde bir wildcard * kullanmayın; bu hem güvenlik riski taşır hem de kimlik bilgisi içeren isteklerle uyumlu değildir:

'allowed_origins' => [
        'https://app.yourapp.com',
    ],
    'allowed_methods' => ['*'],
    'allowed_headers' => ['*'],
    'supports_credentials' => true,
    

supports_credentials ayarı, Sanctum’un çerez tabanlı SPA kimlik doğrulamasını kullanıyorsanız oldukça önemlidir. Bu, tarayıcıya çapraz kaynak isteklerinde çerezlerin dahil edilmesinin güvenli olduğunu söyler.

API Sürümleme

API’niz ayrı bir ön uç sunuyorsa, sürümleme önemli hale gelir. Ön uç ve API bağımsız programlama takvimlerinde dağıtıldığından, API’nizi geliştirirken mevcut ön ucu bozmadan bir yol bulmalısınız.

API rotalarınızı bir sürüm numarası ile ön eklemeniz önerilir. Bunu Laravel’in rota gruplarını kullanarak temiz bir şekilde yapın:

Route::prefix('v1')->group(function () {
        Route::apiResource('projects', ProjectController::class);
        Route::apiResource('deployments', DeploymentController::class);
    });
    

Eloquent API Kaynaklarını kullanarak yanıtlarınızın yapısını kontrol edin. Kaynaklar, model yapınızdan bağımsız bir çıktı formatı sağlayarak içsel yeniden yapılandırmaların API sözleşmenizi bozmamasını temin eder.

Rate Limiting ve Throttling

Açık bir API ile rate limiting uygulamak kaçınılmazdır. Laravel’in yerleşik rate limiting ara yazılımı API’nizi kötüye kullanımdan korur ve kaynak dağılımını adil bir şekilde sağlar. Kimliği doğrulanmış ve kimliği doğrulanmamış istekler için farklı sınırlamalar yapılandırın.

Deploynix’in izleme ve sağlık uyarıları, API sunucunuzun kaynaklarının beklenenden daha hızlı tükendiğinde sizi bilgilendirir. Bu, ya gerçek bir büyümeyi ya da rate limiting’in yakalayamadığı bir saldırıyı gösterebilir.

Ön Uç Kurulumu

Deploynix üzerindeki ön uç dağıtımınız, hangi tür ön uç uygulaması geliştirdiğinize bağlıdır.

Statik SPA (React, Vue, Svelte)

Ön uç uygulamanız, statik HTML, CSS ve JavaScript dosyalarına derleniyorsa, dağıtım son derece basit. Deploynix üzerinde ön uç havuzunuza işaret eden bir site oluşturun. Web dizinini genellikle dist veya build olarak yapılandırın.

Site dağıtım scriptinize her dağıtımda çalışacak olan build komutlarını ekleyin:

npm ci
    npm run build
    

Deploynix, dağıtım sırasında dağıtım scriptinizi çalıştırarak ön uç uygulamanızı sunucuda derler. Ayrıca, Deploynix’in git entegrasyonu aracılığıyla otomatik dağıtımı etkinleştirebilirsiniz; böylece yapılandırılmış dalınıza her itme yapıldığında otomatik olarak bir dağıtım tetiklenir. Nginx yapılandırması statik dosyaları doğrudan sunar ve istemci tarafı yönlendirme için tüm yolları index.html‘ye yönlendiren bir geri dönüş kuralı içerir.

Sunucu Tarafında İşlenmiş (Next.js, Nuxt)

Sunucu tarafında işlenen ön uçlar, kalıcı bir Node.js süreci çalıştırdıkları için daha karmaşıktır. Deploynix üzerinde bunu, Node.js sunucunuzu çalışır durumda tutacak bir daemon kullanarak yapılandırırsınız.

Next.js veya Nuxt uygulamanızı dağıttıktan sonra, Deploynix üzerinden çalışan bir daemon ayarlayın:

npm start
    

Nginx’i, istekleri Node.js sürecine yönlendiren bir ters proxy olarak yapılandırın. Bu, Nginx’in statik dosya sunma ve SSL sonlandırma faydalarından yararlanmanızı sağlarken, Node.js sunucu tarafında işlenen sayfaları yönetebilir.

Site dağıtım scriptiniz, build aşamasını içermelidir:

npm ci
    npm run build
    

Build tamamlandıktan sonra, Deploynix daemonı yeni build’i almak için yeniden başlatabilir.

Kimlik Doğrulama Stratejileri

Seçtiğiniz kimlik doğrulama yaklaşımı, hem dağıtım yapılandırmanızı hem de ön uç kodunuzu etkiler.

Sanctum Token Kimlik Doğrulaması

Mobil uygulamalar, üçüncü taraf entegrasyonları veya API ile aynı alanı paylaşmayan ön uçlar için, token tabanlı kimlik doğrulama en temiz yaklaşımdır. Ön uç, API’ye bir giriş isteği gönderir, bir token alır ve ardışık isteklerinde bu tokenı Authorization başlığında dahil eder.

Bu yaklaşım, kimlik bilgileri için özel CORS yapılandırması gerektirmediğinden, çerez yönetimi veya API tarafında oturum yönetimi gerektirmez. Herhangi bir alan sınırında çalışır ve Deploynix’in kendi API’si için kullandığı, ayrıntılı token kapsamlarıyla uygundur.

Sanctum SPA Kimlik Doğrulaması

Birinci taraf web ön uçları için Sanctum’un SPA kimlik doğrulaması, çerezler ve oturumlar kullanarak kesintisiz bir kimlik doğrulama deneyimi sunar. Akış, bir CSRF tokeni oluşturmak için /sanctum/csrf-cookie isteği ile başlar, ardından bir oturum çerezi ayarlayan bir giriş isteği gelir.

Bu yaklaşım daha dikkatli bir yapılandırma gerektirir. SANCTUM_STATEFUL_DOMAINS‘ınız doğru olmalıdır. CORS yapılandırmanız, kimlik bilgilerini desteklemelidir. Ve ön uç, her istekte kimlik bilgilerini gönderecek şekilde yapılandırılmalıdır.

Avantajı ise daha geleneksel bir kimlik doğrulama modeli sunmasıdır; CSRF koruması, oturum süresi sonlandırması ve çerez güvenliği otomatik olarak yönetilir.

Dağıtım Koordinasyonu

İki bağımsız uygulamayla çalışmak, dağıtım koordinasyonunu gerçek bir sorun haline getirir. Eğer API’niz, ön uç güncellemeye geçmeden önce bir kırılma değişikliği yapıyorsa, kullanıcılar hatalarla karşılaşır.

Strateji 1: API Geriye Dönük Uyumluluğu

En güvenli yaklaşım, API’nizin her zaman geriye dönük uyumlu olmasını sağlamaktır. Bir API yanıtında alan silmeyin veya yeniden adlandırmayın. Mevcut bir uç noktanın geçerli girdilerini reddedecek şekilde doğrulama kurallarını değiştirmeyin. Kırılma değişikliklerini yeni bir önek altında tanıtmak için API sürümlemesini kullanın.

Bu yaklaşım, dağıtım sırasının önemsiz olmasını sağlar. API’niz saat 14:00’te dağıtılabilir ve ön uç saat 16:00’da, arada hiçbir şey kırılmaz.

Strateji 2: Deploynix ile Koordine Dağıtımlar

Koordine değişiklikleri dağıtmanız gerekiyorsa, Deploynix’in planlı dağıtım özelliği API’niz ve ön uç siteleriniz için dağıtımları aynı anda sıraya almanıza olanak tanır. Her iki dağıtımı da aynı dakikada planlayın, API önce dağıtılacak şekilde ayarlayın.

Deploynix’in sıfır kesinti ile dağıtım olanağı, API’nizin atomik olarak geçiş yapmasını sağlar. Eski sürüm, yeni sürüm tam olarak hazır olana kadar istekleri almaya devam eder. Ön uç dağıtımınız birkaç saniye sonra gerçekleşir ve yeni ön uçun eski API ile konuştuğu kısa pencerede API sürümlemenizin geri uyumluluk özelliği devreye girer.

Strateji 3: Özellik Bayrakları

İki uygulamayı etkileyen karmaşık değişiklikler için, özellik bayrakları, her iki tarafta kod dağıtmanıza rağmen bunu etkinleştirmeden yapılmasına olanak tanır. API değişikliklerinizi bir özellik bayrağı arkasında dağıtın. Bayrağı kontrol eden ön uç değişikliklerinizi dağıtın. Ardından, her iki uygulama için aynı anda etkinleştirmek için bayrağı çevirdiğinize emin olun.

Paylaşılan Kaynaklar ve Ortam Değişkenleri

API’niz ve ön uç uygulamanız bazı değerlerde mutabık kalmalıdır. Ön uç, API URL’sini bilmelidir. API’niz, CORS, e-posta bağlantıları ve yönlendirmeler için ön uç URL’sini bilmelidir. Her iki tarafta da ortam değişkenlerinde tutun.

Deploynix üzerinde, her site kendi ortam değişkeni yönetimini içerir. Ön uçta API_URL=https://api.yourapp.com ve API’de FRONTEND_URL=https://app.yourapp.com ayarlarını yapın. Bu, bağlantıyı açık ve yapılandırılabilir hale getirir.

Şifreleme anahtarları veya webhook imzalama anahtarları gibi ortak sırlar için, her iki uygulamanın ortam yapılandırmalarında aynı değeri kullanın. Deploynix, ortam değişkenlerini güvenli bir şekilde saklar ve dağıtım ve çalışma sırasında uygulamanızın erişimine sunar.

SSL ve Alan Adı Yapılandırması

API’nizin ve ön uç uygulamanızın SSL sertifikalarına ihtiyacı vardır. Deploynix, her iki alan için de SSL otomatik tahsisini gerçekleştirir; aynı sunucuda veya farklı sunuculardaysanız da. Eğer api.yourapp.com ve app.yourapp.com gibi alt alan kullanıyorsanız, her iki sertifika bağımsız olarak sağlanır.

Geliştirme ve test ortamları için, Deploynix’in vanity alanı özelliği, otomatik SSL ile *.deploynix.cloud alt alanları sağlar. Test API’niz my-api.deploynix.cloud ve test ön uç uygulamanız my-app.deploynix.cloud üzerinde olacağından, her ikisi de geçerli sertifikalar ile DNS yapılandırması gerekmeksizin kullanılabilir.

Deploynix, DNS tabanlı SSL zorlukları için Cloudflare, DigitalOcean, AWS Route 53 ve Vultr gibi DNS sağlayıcılarını destekler; bu özellikle wildcard sertifikaları için oldukça yararlıdır.

İki Tarafı İzleme

İki uygulama ile çalıştığınızda, Deploynix’in gerçek zamanlı izleme ve sağlık uyarı sistemi daha da önemli hale geliyor. Hem API hem de ön uç siteleriniz için sağlık denetimleri ayarlayın. API’nizin yanıt sürelerini izleyerek performans gerilemelerini kullanıcılarınızdan önce yakalayın.

API’nizin sağlık denetimi, veritabanı bağlantısını, önbellek kullanılabilirliğini ve kuyruk işlemesini doğrulamalıdır. Ön uç uygulamanızın sağlık denetimi, uygulamanın yüklenip yüklenmediğini ve API’ye ulaşma yeteneğini kontrol etmelidir.

Deploynix’in uyarı sistemini yapılandırarak, her iki taraftaki olumsuz gelişmelerde sizi bilgilendirin. API’sine ulaşamayan bir ön uç, çalışmayan bir API kadar bozuk bir durumdur ve her iki tarafa da hâkim olmanız gerekir.

Sonuç

Ayrı bir ön uç ile Laravel API dağıtmak, Deploynix tarafından tamamen desteklenen geçerli bir mimari seçimdir. Anahtar, her iki uygulamayı da altyapınızdaki birinci sınıf vatandaşlar olarak ele almak, her birine kendi dağıtım hattı, izleme ve ölçeklendirme stratejisi vermektir.

Her iki uygulamayı da tek bir sunucuda tutarak işe başlayın. Trafiğiniz arttıkça, onları özel sunuculara ayırarak ortak bir Veritabanı ve Önbellek sunucusuyla çalıştırabilirsiniz. Deploynix’in Yük Dengeleyicisini kullanarak ihtiyaç duyan tarafı ölçeklendirin.

CORS ve kimlik doğrulama yapılandırmanızı baştan doğru ayarlayın. API sürümlemesini kullanarak dağıtım takvimlerinizi ayırın. Deploynix’in dağıtım scriptleri, otomatik dağıtım web kancaları, planlı dağıtımlar ve izleme özelliklerini kullanarak her iki tarafın sağlıklı ve senkronize kalmasını sağlayın.

Ön uç ve arka uç ayrımı, geleneksel bir Laravel uygulamasından daha karmaşık değildir. Farklı bir karmaşıklıktır ve bu karmaşıklığı yönetmenize yardımcı olacak araçlar, bugün Deploynix’te mevcuttur.