Node.js uygulamaları klasik web hostingte nasıl yayınlanır?

Node.js uygulamasını klasik web alanında yayınlamak, PHP tabanlı bir site yüklemekten farklıdır. Çünkü Node.js sürekli çalışan bir süreç, doğru port yönetimi, ortam değişkenleri ve paket bağımlılıkları ister. Bu nedenle ilk adım dosyaları yüklemek değil, kullandığınız panelin Node.js çalıştırmayı gerçekten destekleyip desteklemediğini netleştirmektir.

Klasik hosting ortamında Node.js desteği nasıl anlaşılır?

Paylaşımlı yapılarda her sunucu Node.js uygulaması çalıştırmaya uygun değildir. cPanel üzerinde genellikle Setup Node.js App, Node.js Selector veya Passenger tabanlı bir uygulama yöneticisi bulunur. Bu alan yoksa uygulamayı doğrudan çalıştırmanız çoğu zaman mümkün olmaz.

Kontrol etmeniz gereken temel noktalar şunlardır:

• Node.js sürüm seçimi yapılabiliyor mu?
• Uygulama başlangıç dosyası tanımlanabiliyor mu?
• NPM paketleri panelden veya SSH üzerinden kurulabiliyor mu?
• Ortam değişkenleri eklenebiliyor mu?
• Uygulama yeniden başlatma seçeneği var mı?

Bu özellikler yoksa klasik hosting paketi yerine VPS, bulut sunucu veya Node.js destekli yönetilebilir bir altyapı daha doğru tercih olabilir.

Yayınlama öncesi proje hazırlığı

Uygulamayı sunucuya taşımadan önce yerel ortamda temiz bir çalışma düzeni oluşturmak gerekir. Gereksiz geliştirme dosyaları, test verileri, büyük log dosyaları ve gizli anahtarlar pakete dahil edilmemelidir. package.json dosyanızda başlangıç komutunun doğru tanımlı olması önemlidir.

Express gibi bir yapı kullanıyorsanız uygulamanın sabit bir port yerine panelin verdiği portu okuyacak şekilde hazırlanması gerekir. Genellikle bu değer process.env.PORT üzerinden alınır. Sabit port yazmak, uygulamanın panelde çalışıyor görünmesine rağmen tarayıcıdan erişilememesine neden olabilir.

Dosya yapısında dikkat edilmesi gerekenler

Başlangıç dosyanız genellikle app.js, server.js veya index.js olur. Panelde hangi dosyayı seçtiyseniz proje kökünde o dosyanın bulunması gerekir. Public klasörü, statik dosyalar ve view dosyaları göreli yollarla çağrılmalıdır. Yerel bilgisayara özgü mutlak dosya yolları canlı ortamda hata üretir.

cPanel üzerinden Node.js uygulaması yayınlama adımları

Paneliniz Node.js destekliyorsa süreç genellikle benzer ilerler. Önce uygulama için bir dizin oluşturulur. Ardından Node.js sürümü, uygulama modu, başlangıç dosyası ve alan adı eşleştirmesi seçilir. Bu aşamada üretim ortamı için production modu tercih edilmelidir.

• Proje dosyalarını uygulama dizinine yükleyin.
• Panelde Node.js uygulamasını oluşturun.
• Başlangıç dosyasını doğru seçin.
• NPM install işlemini panelden veya SSH ile çalıştırın.
• Gerekli ortam değişkenlerini ekleyin.
• Uygulamayı yeniden başlatıp hata kayıtlarını kontrol edin.

Burada en sık yapılan hata, node_modules klasörünü yerelden yüklemektir. Farklı işletim sistemi ve Node.js sürümü nedeniyle bu klasör uyumsuzluk yaratabilir. Daha sağlıklı yöntem, bağımlılıkları sunucu üzerinde yeniden kurmaktır.

Alan adı, port ve yönlendirme mantığı

Klasik yapılarda ziyaretçi doğrudan Node.js portuna bağlanmaz. Panel arka planda uygulamayı belirli bir porta yönlendirir ve alan adı üzerinden erişimi yönetir. Bu nedenle uygulama içinde manuel port açmaya, özel reverse proxy ayarı yapmaya veya rastgele port denemeye çalışmak gereksiz sorun çıkarabilir.

Alan adı eşleştirmesinde kök domain, alt alan adı veya belirli bir klasör seçilebilir. API servisleri için genellikle api.domain.com gibi bir alt alan adı daha düzenli bir mimari sağlar. Yönetim paneli veya müşteri arayüzü aynı projede yer alıyorsa statik dosya yolları bu seçime göre kontrol edilmelidir.

Veritabanı ve ortam değişkenleri

Canlı ortama geçerken veritabanı bağlantı bilgileri kodun içine yazılmamalıdır. Kullanıcı adı, şifre, bağlantı adresi, JWT anahtarı ve üçüncü taraf servis anahtarları ortam değişkeni olarak tanımlanmalıdır. Bu yaklaşım hem güvenlik hem de bakım kolaylığı sağlar.

MySQL veya PostgreSQL kullanıyorsanız uzak bağlantı izinlerini, karakter setini ve zaman dilimi ayarlarını kontrol edin. Yerelde çalışan sorgular, canlı sunucuda yetki kısıtları veya farklı SQL modu nedeniyle hata verebilir. İlk kurulumdan sonra basit bir test kaydı ekleyip okuma-yazma işlemlerini doğrulamak zaman kazandırır.

Sık karşılaşılan hatalar ve pratik çözümler

Uygulama çalışıyor ama site açılmıyor

Başlangıç dosyası yanlış seçilmiş, port değeri sabit yazılmış veya alan adı eşleştirmesi yapılmamış olabilir. Paneldeki hata kayıtlarını kontrol edin ve uygulamanın process.env.PORT değerini dinlediğinden emin olun.

NPM install hata veriyor

Node.js sürümü paketlerle uyumlu olmayabilir. Yerelde kullandığınız sürümle paneldeki sürümü karşılaştırın. Native bağımlılık içeren paketlerde derleme aracı eksikliği yaşanabilir; bu durumda daha uyumlu paket sürümü seçmek gerekebilir.

Uygulama bir süre sonra duruyor

Paylaşımlı ortamlarda bellek, işlem süresi veya CPU sınırları bulunur. Yoğun API trafiği, arka plan işleri veya büyük dosya işleme operasyonları klasik yapılar için uygun olmayabilir. Bu senaryolarda kuyruk sistemi, harici dosya depolama veya daha esnek bir sunucu planı değerlendirilmelidir.

Ne zaman farklı bir altyapı tercih edilmeli?

Basit kurumsal API, küçük yönetim paneli veya düşük trafikli bir Node.js projesi klasik ortamda çalışabilir. Ancak gerçek zamanlı socket bağlantıları, uzun süren arka plan görevleri, yüksek eşzamanlı kullanıcı sayısı veya özel sistem servisleri gerekiyorsa klasik hosting sınırlarına takılmanız muhtemeldir.

Yayınlama kararını verirken yalnızca ilk kurulum kolaylığına değil, güncelleme sürecine, hata takibine, yedekleme politikasına ve ölçeklenebilirliğe de bakılmalıdır. Uygulamanızı canlıya almadan önce küçük bir test dağıtımı yapıp logları, yanıt sürelerini ve yeniden başlatma davranışını izlemek, üretim ortamında yaşanabilecek kesintileri büyük ölçüde azaltır.