Node.js uygulamalarının bir VPS'te çalışması gerektiği sanılır. Öyle değil — Rivervo'nun her paylaşımlı hosting paketinde web sitesi menüsünde Node.js ve Python bulunur. Bu bölüm, diğer sitelerinizi sunan aynı Apache ön ucunun arkasında uygulamanız için bir Phusion Passenger süreci başlatır.
Bu rehber, en yaygın iki framework için süreci baştan sona anlatıyor: Next.js ve Nuxt 3. Sonuçta uygulamanız https://alanadiniz.com.tr adresinde (ya da herhangi bir alt alan adında), gerçek bir Node.js sürecinde çalışır, yeniden başlatmalardan etkilenmez ve tek tıkla yeniden başlatılabilir.
Daha önce paylaşımlı hostinge Node uygulaması yayınlamadıysanız herkesin takıldığı yer başlangıç dosyasıdır — Passenger, framework'ünüzü başlatan tek bir giriş betiğine ihtiyaç duyar. Aşağıda her framework için bir tane veriyoruz; kopyalayıp yapıştırın, düzenleme gerekmez.
Başlamadan önce gerekenler
- Bir Rivervo hosting paketi (herhangi biri — Node.js uygulamaları tüm paketlerde çalışır)
- Uygulamanızı derlemek için bilgisayarınızda Node.js v20 ya da daha yenisi
- Yüklemeye hazır derlenmiş çıktı (her framework için aşağıda anlatıyoruz)
- Hesabınıza Dosya Yöneticisi ya da SFTP erişimi (ikisi de olur)
Root, sudo, systemd ya da ters proxy yapılandırmasına ihtiyacınız yok. Bunların hepsini Passenger halleder.
1. adım — uygulamanızı yerelde derleyin
Kaynak kodu değil, derlenmiş uygulamayı yükleyeceksiniz. Panel bağımlılıkları kurar ama React derlemez ya da Vite build çalıştırmaz. Bunu önce kendi bilgisayarınızda yapın.
Next.js:
npm ci
npm run buildBu, .next/ dizinini (derlenmiş çıktı) oluşturur. Burada next start çalıştırmayın — birazdan başlangıç dosyasından başlatacağız.
Nuxt 3:
npm ci
npm run buildBu, .output/ dizinini (Nuxt'ın evrensel derleme dizini) oluşturur. Aynı şekilde — henüz hiçbir şey çalıştırmayın.
2. adım — doğru dosyaları yükleyin
node_modules/ dizinini yüklemeniz gerekmez. Bağımlılıkları panel sizin için kurar. Git ya da derleme önbelleklerine de gerek yok.
Dosyaları hesabınıza, tercihen public_html dışındaki bir yola yükleyin (ör. /home/<hesap>/myapp/). Neden dışarıya? Çünkü Passenger public_html dizinini otomatik olarak adresin köküne bağlar ve uygulama kodunuzu oraya koymak onu herkese açar.
| Framework | Bunları yükleyin | Bunları atlayın |
|---|---|---|
| Next.js | .next/, public/, package.json, package-lock.json, next.config.js, server.cjs dosyanız (aşağıda) | node_modules/, .git/, .env.local |
| Nuxt 3 | .output/, package.json, package-lock.json, server.cjs dosyanız (aşağıda) | node_modules/, .nuxt/, .git/, kaynak pages/, components/ |
Dosyaları iki yolla yükleyebilirsiniz:
- Bağlantınız kararsızsa en kolayı Web sitesi → Dosyalar → zip yükleyin → açın yoludur.
- Tekrarlanan yayınlar için SFTP (FileZilla, Cyberduck,
rsync) daha hızlıdır. Sunucu, port, kullanıcı adı ve şifre Web sitesi → SSH ve SFTP sayfasındadır.
3. adım — başlangıç dosyasını ekleyin
Bir istek geldiğinde Passenger'ın çalıştırdığı dosya budur. Uygulama klasörünüzde package.json dosyasının yanına koyun.
Next.js için — server.cjs
const next = require('next')
const http = require('http')
const port = process.env.PORT || 3000
const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev, dir: __dirname })
const handle = app.getRequestHandler()
app.prepare().then(() => {
http.createServer((req, res) => handle(req, res)).listen(port, () => {
console.log(`Next.js server listening on port ${port}`)
})
})Ne yapar:
- Next'i yükler ve geçerli dizini (
.next/vepackage.jsondosyalarınızın bulunduğu yer) gösterir. - Next'in iç yönlendiricisinden bir istek işleyici oluşturur.
- Passenger'ın atadığı portta (
process.env.PORT) bir HTTP sunucusu başlatır. - Yerel test için
3000portuna geri döner.
dev değeri NODE_ENV üzerinden otomatik belirlenir — panelde Production modunu seçin (4. adımda yapacağız), Next üretim modunda çalışır.
Nuxt 3 için — server.cjs
import('./.output/server/index.mjs').then(({ createApp }) => {
createApp().then(({ app }) => {
const port = process.env.PORT || 3000
app.listen(port, () => {
console.log(`Nuxt server listening on port ${port}`)
})
})
})Ne yapar:
- Nuxt'ın
.output/server/index.mjsdosyasını (npm run buildile oluşan giriş dosyası) dinamik olarak içe aktarır. - H3 sunucu örneğini oluşturmak için
createApp()kullanır. - Passenger'ın atadığı portu dinler.
Dinamik import() bilinçli bir tercihtir — .mjs modülleri require() ile yüklenemez, ancak bir .cjs dosyası onları dinamik olarak içe aktarabilir. Passenger'ın başlatıcısı içinde çalışan en temiz yöntem budur.
4. adım — uygulamayı panelde oluşturun
Projenizi açın → Web sitesi → Node.js ve Python → Node.js uygulaması.
| Alan | Değer |
|---|---|
| Sürüm | 20 ya da daha yenisi |
| Mod | Production |
| Klasör | ana klasörünüzdeki myapp (dosyaları yüklediğiniz yer) |
| Adres | alanadiniz.com.tr (ya da app.alanadiniz.com.tr gibi bir alt alan adı) |
| Başlangıç dosyası | server.cjs |
Oluştur'a tıklayın. ~/nodevenv/myapp/20/ altında bir Node.js ortamı oluşturulur.
Bağımlılıkları kurun
Uygulama oluşturulduktan sonra üzerindeki Bağımlılıkları kur (npm install) düğmesine tıklayın ve çıktıyı izleyin. Başarısız olursa:
package.jsondosyasının uygulamanın kök dizininde olduğunu (alt klasörde olmadığını) kontrol edin.- Next.js için:
nextpaketinindevDependenciesiçinde değil,dependenciesiçinde olduğundan emin olun (üretim kurulumu geliştirme bağımlılıklarını atlar). - Nuxt için:
nuxtpaketi de normal bir bağımlılık olmalıdır.
Ortam değişkenlerini ekleyin
Uygulamanın Ayarlar → Ortam değişkenleri → Değişken ekle. Production modu NODE_ENV=production değerini zaten ayarlar.
Çalışma zamanında değer okuyan Next.js uygulamaları için (veritabanı adresleri, API anahtarları) değerleri buraya ekleyin. Gizli bilgiler içeren bir .env dosyası yüklemeyin — doğru yer uygulamanın ortam değişkenleridir.
Ayarları kaydetmek uygulamayı yeniden başlatır, böylece yeni değişkenler hemen geçerli olur.
5. adım — doğrulayın
Uygulamanızın adresini açın. Uygulamanızı görmelisiniz.
Bir Passenger hata sayfası görürseniz onu genişletip en alta bakın — neredeyse her zaman açık bir hata izi vardır. En yaygın iki hata:
Error: Cannot find module 'next' — npm install çalışmadı ya da yanlış klasörde çalıştı. Bağımlılıkları kur (npm install) düğmesine tekrar tıklayın.
Error: ENOENT: no such file or directory, open '.next/...' — kaynak kodu yüklediniz ama derlenmiş .next/ dizinini yüklemediniz. Yerelde derleyip yeniden yükleyin.
Güncellemeler nasıl yayınlanır
Birinci ve ikinci adımları tekrarlayın ve uygulamada Yeniden başlat'a tıklayın. Yani:
1. Yerelde derleyin npm run build
2. Yükleyin .next/ ya da .output/ ve değişen kaynak/ayar dosyaları
3. Panel Uygulamayı yeniden başlatınpackage.json dosyasını değiştirirseniz yeniden başlatmadan önce Bağımlılıkları kur (npm install) düğmesine tıklayın. Komut satırını mı tercih edersiniz? Web sitesi → Terminal: uygulama kartı, ortamına girmek için gereken komutu gösterir.
Sık karşılaşılan tuzaklar
WebSocket: Passenger HTTP/1.1 ve HTTP/2'yi destekler. WebSocket yükseltmesi Next.js ve Nuxt'ın yerleşik yollarında çalışır. Ayrı bir WebSocket sunucusu (ws, socket.io) kullanıyorsanız aynı portu paylaşır ve aynı server.cjs ile başlar — ek ayar gerekmez.
Dosya yükleme / next.config.js body-parser sınırları: Passenger'ın varsayılan istek gövdesi sınırı 10 MB'tır. Büyük dosyalar yüklüyorsanız public_html içindeki .htaccess ile passenger_max_request_size değerini yükseltin:
PassengerMaxRequestSize 52428800(Bayt cinsinden 50 MB.)
Cron görevleri: uygulamanızın arka plan görevleri varsa (bülten gönderimleri, zamanlanmış dışa aktarmalar) bunları web süreci içinde çalıştırmayın. Bir Node betiğini doğrudan çağırmak için Web sitesi → Cron görevleri bölümünü kullanın:
/home/<hesap>/nodevenv/myapp/20/bin/node /home/<hesap>/myapp/scripts/send-newsletter.jsSüreç belleği: uygulamanız hesap başına RAM sınırını (paketinize bağlıdır) aşarsa Passenger onu yeniden başlatır. Tipik bir Next.js / Nuxt uygulaması boşta 100 MB'ın altında kullanır. Sınıra takılıyorsanız daha büyük bir pakete ihtiyacınız olduğunu düşünmeden önce process.memoryUsage() ile profil çıkarın ve sızıntı arayın.
Özel alan adları ve HTTPS: uygulamaya atadığınız adres, Passenger'ın bağlandığı adrestir. SSL otomatiktir — ek ayar gerekmez. Başka bir alan adı ya da alt alan adı için önce Web sitesi → Alan adları altında ekleyin, sonra uygulamanın adresi olarak seçin.
Node sürümü: Sürüm listesi kurulu tüm sürümleri gösterir; sürümü uygulamanın Ayarlar bölümünden değiştirebilirsiniz.
Node için paylaşımlı hosting ne zaman uygun değildir
Açık konuşalım — paylaşımlı hostingde Node.js; portfolyo siteleri, bloglar, tanıtım sayfaları, küçük SaaS ön yüzleri ve iç araçlar için çok iyi çalışır. Şunlarda zorlanır:
- Yüksek hacimli API'ler (sürekli >50 istek/sn) — hesap başına CPU sınırını hissedersiniz
- Binlerce eşzamanlı bağlantıya sahip yoğun WebSocket uygulamaları
- Alt süreç başlatan uygulamalar (kuyruk işçileri, kazıyıcılar) — Passenger'ın hesap başına süreç sınırı bunu zorlaştırır
- systemd, Docker ya da root erişimi gerektiren her şey
Bunlar için doğru tercih VPS'imizdir — tam root, kendi çekirdeğiniz, istediğiniz her şeyi çalıştırır. Ancak çok yüksek trafik almayan çoğu Next.js ve Nuxt uygulaması için bu rehber yeterlidir.
Özetle
- Yerelde
npm run build .next/(Next) ya da.output/(Nuxt) +package.json+server.cjsyükleyin- Web sitesi → Node.js ve Python → Node.js uygulaması → klasör, başlangıç dosyası
server.cjs, mod Production - Bağımlılıkları kur (npm install), ardından Yeniden başlat
Bir şey ters giderse destek talebi açın — Passenger hata sayfasını yapıştırın, sorunlu satırı gösterelim.
— Rivervo Ekibi