Next.js'i Passenger ile shared veya dedicated cPanel hesabında çalıştırmak; build artefaktı, Node sürümü, environment dosyası, staging yolu ve restart sırası için açık bir değişiklik planı ister. Yanlış eşleşme 502 hatasına veya hizmet etkisine yol açabilir; süre sabit değildir. Bu kontrol listesi Peykan (peykan.com.tr) örneğinde kullanılan ve benzer kurulumlara kapsam doğrulandıktan sonra uyarlanabilen deseni anlatır.
1. output: 'standalone' uygunluğunu doğrulayın
next.config içindeki output: 'standalone', runtime için gereken server dosyalarını .next/standalone altında toplar; public ve static varlıklar ayrıca kopyalanır. Bu ayrım aktarılan veri miktarını azaltabilir, ancak gerçek paket boyutu ve deploy süresi bağımlılıklar, build çıktısı, ağ ve disk hızıyla ölçülmelidir.
2. Staging yolu: kapasiteyi ve yaşam döngüsünü doğrulayın
cPanel sunucularında /tmp ve /var/tmp kapasitesi ile mount yapısı değişebilir; build almadan önce df/mount çıktısını ve hesap kotasını doğrulayın. Staging için hesap altında erişimi sınırlı bir release dizini kullanılabilir. Başarılı swap sonrası geçici dosyalar temizlenir; tutulacak geri dönüş kopyası sayısı depolama, saklama politikası ve kurtarma ihtiyacına göre belirlenir.
3. Node sürümü pin
Passenger, hesabın seçili CloudLinux Node ortamını kullanır. Build ve runtime ana sürümleri uyuşmadığında native modül, fetch/Undici veya paket davranışı farklılaşabilir. Deploy script'i desteklenen sürüm aralığını ve node -v çıktısını doğrulamalı; uyumsuzlukta kontrollü olarak durmalıdır.
4. .env.production sunucuda kalır
Secret'ları git'e koymayın; rsync --exclude ile .env'i atlayın. Sunucudaki .env.production'ı stage'e kopyalayıp yeni release'e taşıyın. DATABASE_URL veya SMTP değiştiyse önce smoke test, sonra symlink swap.
5. Atomic swap + Passenger restart
- Yeni release'i stage dizininde hazırla
- current → previous, stage → current (ln -sfn veya mv)
- tmp/restart.txt dokunarak Passenger'ı soft restart et
- curl -I ve kritik route smoke test
- Hata varsa previous'a geri al, restart tekrar
6. Static asset hash uyumu
Yeni build eski asset hash'lerini kaldırdığında, önbellekteki HTML bir süre eski CSS/JS URL'lerini isteyebilir. Release tasarımında örtüşen asset saklama, atomik HTML geçişi veya kontrollü cache invalidation yöntemlerinden uygun olanını seçin. Deploy gate'i kritik asset URL'lerini doğrulamalı; eski dosyalar kaynağı ve sürümü doğrulanmadan yeni pakete kopyalanmamalıdır.
Peykan (peykan.com.tr) dahil bu desende release; ayrı bir alanda hazırlanır, smoke test sonrası kontrollü olarak devreye alınır ve geri dönüş yolu korunur. Gerçek deploy süresi ile kesinti riski; build boyutu, sunucu kaynakları, veri değişikliği ve restart davranışına göre her geçişte ölçülür. Canlı referans: https://aior.com/referanslar/peykan
