VPS’te Node.js Uygulaması Kurma ve Yayınlama

Okuma süresi: 6 dk

Bu rehber kimin için: Node.js geliştiricileri · Gereken süre: 15 dakika · Seviye: İleri

Paylaşımlı hosting paketlerimizde Node.js uygulama yöneticisi, SSH ve cPanel Terminal bulunmaz; bu yüzden Express, NestJS ya da Next.js sunucu modu gibi sürekli çalışan Node.js uygulamaları paylaşımlı hostingte yayınlanamaz. Bu iş için kendi işletim sisteminiz ve root yetkiniz olan bir VPS gerekir: Node.js’i kurar, uygulamayı bir süreç yöneticisiyle ayakta tutar ve web trafiğini Nginx üzerinden uygulamaya iletirsiniz. VPS’te WebSocket bağlantıları ve sürekli çalışan arka plan işleri de aynı şekilde çalışır. Komutlar Ubuntu 24.04 LTS içindir; VPS paketlerimizde Debian 12, AlmaLinux 9 ve Rocky Linux 9 de seçilebilir.

VPS’e Node.js kurma

VPS’te Node.js’i kendiniz kurarsınız. Ubuntu 24.04 deposundaki nodejs paketi, Node.js projesinin desteğini bitirdiği 18 serisindendir; üretim için güncel LTS sürümünü NodeSource deposundan kurun.

1. VPS’e sudo yetkili kullanıcınızla SSH ile bağlanın; sunucuyu yeni aldıysanız önce Ubuntu VPS ilk kurulum adımlarını tamamlayın.
2. Paket listesini güncelleyin: sudo apt update && sudo apt upgrade -y
3. NodeSource kurulum betiğini indirin: curl -fsSL https://deb.nodesource.com/setup_lts.x -o nodesource_setup.sh
4. Betiği çalıştırmadan önce less nodesource_setup.sh ile içeriğine göz atın, ardından sudo -E bash nodesource_setup.sh komutuyla depoyu ekleyin.
5. Node.js’i kurun: sudo apt install -y nodejs (npm bu pakete dahildir).
6. Sürümleri doğrulayın: node -v ve npm -v

Aynı sunucuda farklı projeler farklı Node.js sürümleri istiyorsa sürümleri kullanıcı bazında yöneten nvm aracını da kullanabilirsiniz; bu durumda PM2’yi ve uygulamayı aynı kullanıcıyla çalıştırın.

Uygulama oluşturma

1. Dosyaları yükleyin: Uygulama dosyalarınızı git clone, scp ya da SFTP ile sunucuda web kökü dışındaki bir klasöre (ör. /srv/uygulamam) aktarın; node_modules klasörünü aktarmayın, bağımlılıklar sunucuda kurulur.
2. Uygulamayı tanımlayın: PM2’yi sudo npm install -g pm2 ile kurun; uygulamanın adını, başlangıç dosyasını ve çalışma klasörünü pm2 init simple komutunun oluşturduğu ecosystem.config.js dosyasında tanımlayın (name, script ve cwd alanları).
3. Klasör ve adresi girin: ecosystem.config.js içindeki cwd alanına uygulama klasörünü (ör. /srv/uygulamam) yazın; alan adını ise Nginx sunucu bloğundaki server_name satırında tanımlarsınız (aşağıdaki bölüm).
4. Başlangıç dosyası: script alanına app.js veya server.js gibi giriş dosyanızı yazın; package.json’daki start betiğiyle çalışan çatılarda (ör. Next.js) script alanına npm, args alanına start yazın.
5. Ortam değişkenleri: Veritabanı bilgileri ve API anahtarlarını ecosystem.config.js içindeki env bölümünde (ör. NODE_ENV: "production", PORT: 3000) ya da yalnız uygulama kullanıcısının okuyabildiği bir .env dosyasında tutun; koda gömmeyin ve bu dosyaları depoya eklemeyin.
6. Bağımlılıkları kurun: Uygulama klasöründe npm ci --omit=dev ile bağımlılıkları kurun (derleme adımı varsa önce npm ci ile tüm bağımlılıkları kurup npm run build çalıştırın), ardından pm2 start ecosystem.config.js ile uygulamayı başlatıp pm2 status ile çalıştığını kontrol edin.

Port ayarı

VPS’te portu siz belirlersiniz. Uygulamanın yalnız sunucu içinden erişilen bir adresi dinlemesini sağlayın (ör. Express’te app.listen(process.env.PORT, "127.0.0.1")) ve portu kodda process.env.PORT ile okuyun; dışarıya açılan 80 ve 443 portlarını Nginx dinler. Node.js sürecini root olarak çalıştırmayın. UFW kullanıyorsanız 3000 portunu açmayın, yalnız SSH ve web portlarına izin verin. Aynı sunucuda birden fazla uygulama çalıştıracaksanız her birine ayrı bir port verin.

PM2’yi kalıcı yapma ve Nginx ile yayınlama

PM2, uygulama çökerse onu yeniden başlatır. Sunucu yeniden açıldığında uygulamaların kendiliğinden kalkması için PM2’yi sistem açılışına bağlarsınız; Nginx de 80 ve 443 portlarına gelen istekleri uygulamaya iletir.

1. pm2 startup komutunu sudo olmadan çalıştırın; çıktıda gösterilen ve sudo env PATH= ile başlayan satırı kopyalayıp çalıştırın.
2. Çalışan uygulama listesini kaydedin: pm2 save
3. Nginx’i kurun: sudo apt install -y nginx
4. sudo nano /etc/nginx/sites-available/uygulamam ile bir sunucu bloğu oluşturun: listen 80; ve server_name alanadiniz.com www.alanadiniz.com; satırlarının altına, aşağıdaki tablodaki yönergeleri içeren bir location / { } bloğu ekleyin.
5. Siteyi etkinleştirin: sudo ln -s /etc/nginx/sites-available/uygulamam /etc/nginx/sites-enabled/ ardından sudo nginx -t && sudo systemctl reload nginx
6. Alan adınızın A kaydını VPS’in IP adresine yönlendirin, web portlarını açın (sudo ufw allow "Nginx Full") ve Certbot ile SSL kurun: sudo certbot --nginx -d alanadiniz.com -d www.alanadiniz.com

Sunucu bloğunun genel yapısı ve PHP siteleriyle birlikte kullanımı Nginx kurulumu rehberinde. VPS yönetimsiz teslim edilir; Node.js, Nginx ve SSL gibi sunucu tarafı kurulumları, güncellemeleri ve izlemeyi ekibimize bırakmak isterseniz sunucu yönetimi hizmetini ekleyebilirsiniz.

Hâlâ çözülmediyse

Nginx “502 Bad Gateway” hatası veriyorsa uygulama çalışmıyordur ya da proxy_pass satırındaki port, uygulamanın dinlediği portla aynı değildir. pm2 status ile sürecin durumuna, pm2 logs uygulamam ile son hatalara, sudo tail -n 50 /var/log/nginx/error.log ile Nginx kayıtlarına bakın; en sık nedenler eksik bağımlılık, yanlış başlangıç dosyası ve tanımlanmamış ortam değişkenidir. Bu kurulum için VPS sunucu gerekir; paylaşımlı hosting paketlerimizde Node.js uygulaması çalıştırılamaz.

Sık sorulan sorular

İlgili rehberler

• VPS’te Python (Django, Flask) Uygulaması Kurma
• Git ile VPS’e Otomatik Dağıtım
• cPanel Kaynak Kullanımı: CPU, RAM ve EP Limitleri