Node.js Uygulamasını Sunucuda Yayınlama: PM2 ve Nginx
Node.js uygulaması sunucuya nasıl yüklenir? Node.js LTS, npm ci, PM2 ile otomatik başlatma ve reload, Nginx ters vekil, HTTPS, güncelleme ve sık hatalar.

İçindekiler
- Gereksinimler
- 1. Adım: Node.js LTS, PM2 ve Nginx
- 2. Adım: Kullanıcı, kod ve npm ci
- 3. Adım: Ortam değişkenleri ve dinleme adresi
- 4. Adım: Uygulamayı PM2 ile çalıştırma
- 5. Adım: Açılışta başlatma
- 6. Adım: Cluster modu
- 7. Adım: Nginx ters vekil sunucusu
- 8. Adım: Güvenlik duvarı ve HTTPS
- Güncellemeleri yayınlamak
- Günlükler ve sık karşılaşılan hatalar
- Next.js, Nuxt ve NestJS hakkında bir not
- Node.js uygulamaları için Nodesty sunucuları
Bir Node.js uygulamasını sunucuya yüklemek için SSH oturumunda node server.js çalıştırmak yetmez: Oturum kapanınca uygulama durur, çökünce kapalı kalır ve sunucu yeniden başladığında geri gelmez. Linux VDS üzerinde alışılmış kurulum, uygulamayı ayakta tutan süreç yöneticisi olarak PM2 ve önünde HTTPS ile WebSocket bağlantılarından sorumlu ters vekil sunucusu (reverse proxy) olarak Nginx'tir. Bu yapı bir kez kurulduğunda her güncelleme birkaç komuta iner.
Bu rehberde temiz bir Ubuntu sunucuda, örneğin bir Express API'si gibi bir Node.js uygulamasını yayınlamayı anlatıyoruz: Node.js LTS kurulumu, ayrı bir kullanıcı, npm ci, ortam değişkenleri, PM2 ile otomatik başlatma ve cluster modu, Nginx ters vekil sunucusu, güvenlik duvarı, HTTPS, güncellemeler ve en sık karşılaşılan hatalar.
Gereksinimler
- Sunucu: Root erişimli bir Ubuntu sunucu. Bu rehberde Ubuntu 24.04 kullanıyoruz.
- Uygulama: Git deposunda duran,
package.jsonvepackage-lock.jsondosyaları olan bir Node.js projesi. - Alan adı: Sunucunuzun IP adresini gösteren bir A kaydı.
HTTP isteği karşılamayan bir botun Nginx'e ihtiyacı yoktur; bu durum için Discord botu 7/24 nasıl aktif tutulur? rehberimize bakın.
1. Adım: Node.js LTS, PM2 ve Nginx
Sunucunuza SSH ile bağlandıktan sonra:
sudo apt update
sudo apt install nginx git curl
curl -fsSL https://deb.nodesource.com/setup_lts.x -o nodesource_setup.sh
sudo -E bash nodesource_setup.sh
sudo apt install nodejs
sudo npm install -g pm2
node -v && npm -v && pm2 -v
Ubuntu 24.04'ün kendi depolarında, desteği sona ermiş olan Node.js 18 bulunur. NodeSource deposu ise güncel LTS sürümünü npm ile birlikte, tüm sistem için /usr/bin/node olarak kurar; tek bir ana sürümde kalmak için setup_lts.x yerine örneğin setup_24.x yazın. Sunucularda bunu nvm'e tercih ediyoruz: nvm, Node.js'i tek bir kullanıcının ev klasörüne kurar ve bu da servisler ile otomatik başlatma için gereken yolları doğru ayarlamayı zorlaştırır.
AlmaLinux'ta curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash - komutunu, ardından sudo dnf install nodejs nginx git komutunu çalıştırın. Orada Nginx nginx kullanıcısıyla çalışır ve site dosyaları /etc/nginx/conf.d/ klasörüne konur. Temel bilgiler için Nginx kurulumu rehberimize bakın.
2. Adım: Kullanıcı, kod ve npm ci
Uygulamayı root olarak çalıştırmayın. Onun için bir kullanıcı ve /srv altında bir klasör oluşturun:
sudo adduser --disabled-password --gecos "" deploy
sudo mkdir -p /srv/app
sudo chown deploy:deploy /srv/app
sudo -iu deploy
git clone git@github.com:user/app.git /srv/app
cd /srv/app
npm ci
npm run build # yalnızca projenizde derleme adımı varsa
npm ci, node_modules klasörünü siler ve tam olarak package-lock.json dosyasında kayıtlı sürümleri kurar; böylece sunucuya test ettiğiniz paketlerin aynısı gelir. Kilit dosyası ile package.json uyuşmuyorsa hata vererek durur. Projede derleme adımı yoksa npm ci --omit=dev komutu geliştirme bağımlılıklarını atlar. Deploy anahtarlarını Git ile deploy rehberimizde, kullanıcı yönetimini Linux'ta kullanıcı ekleme yazımızda anlatıyoruz. Sonraki adımlardaki komutları, sudo ile başlamıyorsa deploy kullanıcısıyla çalıştırın.
3. Adım: Ortam değişkenleri ve dinleme adresi
Gizli bilgileri koddan ve depodan uzak tutun. /srv/app/.env dosyasını oluşturun, .gitignore dosyasına ekleyin ve chmod 600 .env ile koruyun:
SESSION_SECRET=uzun-rastgele-bir-degeri-buraya-yapistirin
DATABASE_URL=postgres://app:guclu-bir-parola@127.0.0.1:5432/app
Uygun bir rastgele değeri openssl rand -hex 32 komutuyla üretebilirsiniz. Node.js 20.6 ve sonrası bu dosyayı --env-file bayrağıyla yükleyebilir, yani ek bir pakete gerek yoktur; projeniz zaten dotenv kullanıyorsa o da olur. Değerleri process.env ile okuyun ve uygulamanın yalnızca yerel adresi dinlemesini sağlayın:
const port = Number(process.env.PORT) || 3000;
app.set('trust proxy', 1); // Express: Nginx'in gönderdiği X-Forwarded-* başlıklarına güven
app.listen(port, '127.0.0.1');
Adres belirtilmezse Node.js tüm ağ arayüzlerini dinler; bu durumda uygulama Nginx'i atlayarak ve HTTPS olmadan http://SUNUCU-IP:3000 adresinden de cevap verir. Şimdi test edin:
node --env-file=.env server.js
İkinci bir SSH oturumundan curl -I http://127.0.0.1:3000 komutu bir cevap döndürmelidir. Uygulamayı Ctrl+C ile durdurun.
4. Adım: Uygulamayı PM2 ile çalıştırma
Uygulamayı /srv/app/ecosystem.config.js dosyasında tanımlayın; böylece ayarlar uzun bir komut yerine bir dosyada durur:
module.exports = {
apps: [
{
name: 'app',
script: 'server.js',
cwd: '/srv/app',
node_args: '--env-file=.env',
env: {
NODE_ENV: 'production',
PORT: 3000,
},
},
],
};
pm2 start ecosystem.config.js
pm2 status
package.json dosyanızda "type": "module" varsa dosyanın adını ecosystem.config.cjs yapın. En çok kullanacağınız komutlar:
| Komut | Ne yapar |
|---|---|
pm2 status | Süreçleri durumları, yeniden başlama sayıları (↺) ve bellekleriyle listeler |
pm2 logs app | Uygulamanın çıktısını canlı izler; dosyalar ~/.pm2/logs/ klasöründedir |
pm2 reload app | Yeni kodu başlatır; cluster modunda süreçleri tek tek yeniler |
pm2 restart app | Uygulamanın tüm süreçlerini aynı anda durdurup başlatır |
pm2 stop app / pm2 delete app | Uygulamayı durdurur / PM2 listesinden kaldırır |
pm2 monit | CPU, bellek ve günlükleri terminalde canlı gösterir |
Bilmeniz gereken iki nokta var:
- Ortam: PM2,
envdeğerlerini ilk başlatmadaki haliyle hatırlar. Bunları değiştirdikten sonrapm2 reload ecosystem.config.js --update-envkomutunu çalıştırın; yalnızcapm2 reload appeski değerleri korur..envdosyası ise her başlatmada yeniden okunur, orada normal bir reload yeterlidir. - Günlükler: PM2'nin günlük dosyaları sınırsız büyür.
pm2 install pm2-logrotatekomutu otomatik döndürme ekler; böylece günlükler diski doldurmaz.
5. Adım: Açılışta başlatma
Sunucu açıldığında PM2'nin kendisi de başlamalı ve uygulamalarınızı geri getirmelidir. Süreç listesini deploy kullanıcısıyla kaydedin, ardından yönetici hesabınıza dönüp PM2'yi bu kullanıcı için bir systemd servisi olarak kaydedin:
pm2 save
exit
sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u deploy --hp /home/deploy
pm2 startup, pm2-deploy adında bir servis oluşturup etkinleştirir; bu servis açılışta pm2 save komutunun /home/deploy/.pm2/dump.pm2 dosyasına yazdığı listeyi geri yükler. Uygulama ekleyip çıkardığınızda pm2 save komutunu yeniden çalıştırın. Emin olmak için sunucuyu bir kez sudo reboot ile yeniden başlatın ve deploy kullanıcısıyla pm2 status çıktısına bakın. Uygulamayı yalnızca systemd ile yönetmeyi tercih ederseniz systemd servisi oluşturma rehberimize bakın.
6. Adım: Cluster modu
Bir Node.js süreci JavaScript kodunuzu tek bir CPU çekirdeğinde çalıştırır. Cluster modunda PM2, uygulamanın aynı portu paylaşan birden fazla kopyasını başlatır. ecosystem.config.js dosyasındaki uygulama tanımına iki satır ekleyin:
instances: 'max',
exec_mode: 'cluster',
max, CPU çekirdeği başına bir süreç başlatır; bir sayı da yazabilirsiniz. Mod değiştirmek için uygulamayı baştan başlatmanız gerekir: pm2 delete app, ardından pm2 start ecosystem.config.js ve pm2 save. Bundan sonra pm2 reload app süreçleri tek tek, kesinti olmadan yeniler.
- Bellekte durum tutmayın: Bir değişkende tutulan oturumlar, önbellekler ya da hız sınırı sayaçları her süreçte ayrı ayrı bulunur. Bunları veritabanına ya da Redis'e taşıyın. Birden fazla süreç çalışırken Socket.IO ayrıca yapışkan oturumlara (sticky session) ihtiyaç duyar.
- Temiz kapanış: Reload sırasında PM2 eski sürece
SIGINTgönderir ve varsayılan olarak 1,6 saniye sonra süreci sonlandırır (kill_timeout). Açık istekleri tamamlamak ve veritabanı bağlantılarını kapatmak için bu sinyali yakalayın. - Bellek: Her süreç kendi RAM'ini kullanır. Uygulama az CPU işi yapıyorsa çoğu zaman bir ya da iki süreç yeterlidir.
7. Adım: Nginx ters vekil sunucusu
/etc/nginx/sites-available/app dosyasını oluşturun:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
listen [::]:80;
server_name example.com www.example.com;
client_max_body_size 20M;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}
sudo ln -s /etc/nginx/sites-available/app /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
- Vekil başlıkları:
Host,X-Real-IP,X-Forwarded-ForveX-Forwarded-Protobaşlıkları uygulamaya hangi alan adının istendiğini, ziyaretçinin kim olduğunu ve isteğin HTTPS üzerinden gelip gelmediğini bildirir. Bunlar olmadan her istek127.0.0.1adresinden gelen düz HTTP gibi görünür. - WebSocket:
proxy_http_version 1.1ileUpgradeveConnectionbaşlıkları WebSocket bağlantılarının (Socket.IO, canlı güncellemeler) geçmesini sağlar.mapbloğu,Connection: upgradebaşlığını yalnızca tarayıcı istediğinde gönderir. - Zaman aşımı: Nginx, 60 saniye boyunca sessiz kalan vekil bağlantısını kapatır (
proxy_read_timeout). WebSocket için düzenli ping mesajları gönderin ya da bu değeri artırın. client_max_body_size: Nginx varsayılan olarak 1 MB yüklemeye izin verir; daha büyük istekler 413 hatası alır.localhostyerine127.0.0.1:localhostaynı zamanda uygulamanın dinlemediği IPv6 adresi::1olarak da çözümlenir.
AlmaLinux'ta dosyayı /etc/nginx/conf.d/app.conf olarak kaydedin ve sudo setsebool -P httpd_can_network_connect 1 komutuyla Nginx'in yerel portlara bağlanmasına izin verin; aksi halde SELinux vekil bağlantısını engeller ve 502 hatası alırsınız.
8. Adım: Güvenlik duvarı ve HTTPS
Yalnızca SSH ve web portlarını açın. 3000 portu kapalı kalır:
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
SSH farklı bir portta çalışıyorsa güvenlik duvarını etkinleştirmeden önce o porta izin verin; yoksa sunucuya erişiminizi kaybedersiniz. Ayrıntılar için UFW kullanımı rehberimize bakın. AlmaLinux'ta sudo firewall-cmd --permanent --add-service=http --add-service=https ve ardından sudo firewall-cmd --reload komutlarını kullanın. Sonra sertifikayı alın:
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d example.com -d www.example.com
Certbot sertifikayı alır, HTTPS sunucu bloğunu ekler ve otomatik yenilemeyi ayarlar. Ayrıntılar için SSL sertifikası nedir? yazımıza bakın.
Güncellemeleri yayınlamak
sudo -iu deploy
cd /srv/app
git pull
npm ci
npm run build # yalnızca projenizde derleme adımı varsa
pm2 reload app
Çalışan süreçler reload komutuna kadar eski kodu bellekte tutar. Ardından pm2 status ve pm2 logs app --lines 50 çıktısına bakın: Sürekli artan bir yeniden başlama sayısı (↺), yeni sürümün açılırken çöktüğünü gösterir. npm ci, eski sürüm hâlâ çalışırken node_modules klasörünü baştan kurduğu için büyük projeler her sürümü ayrı bir klasörde hazırlar; bu yöntemi ve bir deploy betiğini Git ile deploy rehberimizde gösteriyoruz. Veriyi değiştiren migration'lardan önce veritabanını yedekleyin; sunucu yedekleme rehberimize bakın.
Günlükler ve sık karşılaşılan hatalar
Uygulamanın çıktısını pm2 logs app ile görürsünüz; Nginx ise /var/log/nginx/error.log dosyasına yazar.
| Hata | Sık görülen neden |
|---|---|
| 502 Bad Gateway | Uygulama çalışmıyor ya da sürekli çöküyor (pm2 status içinde errored) ya da proxy_pass yanlış portu gösteriyor |
EADDRINUSE: address already in use | 3000 portunu başka bir süreç tutuyor; çoğu zaman elle başlatılmış bir node server.js ya da root ile çalışan ikinci bir PM2 |
Site http://SUNUCU-IP:3000 ile açılıyor | Uygulama 127.0.0.1 yerine 0.0.0.0 ya da :: adresini dinliyor ve güvenlik duvarı açık |
Dinlerken EACCES: permission denied | Uygulama normal kullanıcıyla 1024'ten küçük bir portu kullanmaya çalışıyor; 3000 kullanın, 80 ve 443 Nginx'te kalsın |
npm ci ya da dosya yazarken EACCES | sudo npm ya da sudo git pull sonrası dosyalar root'a ait |
Cannot find module | Güncellemeden sonra npm ci çalıştırılmamış ya da cwd yanlış klasörü gösteriyor |
| Yeniden başlatmadan sonra uygulama yok | pm2 startup hiç kurulmamış ya da son değişiklikten sonra pm2 save çalıştırılmamış |
- Port kullanımda:
sudo ss -tlnp | grep :3000komutu portu hangi sürecin tuttuğunu gösterir. Gerisini port kullanımda hatası rehberimizde anlatıyoruz. - 127.0.0.1 mi 0.0.0.0 mı: Nginx aynı sunucudaysa doğru adres
127.0.0.1adresidir. Uygulamanın0.0.0.0adresini dinlemesi yalnızca Docker konteynerinde çalışıyorsa ya da Nginx başka bir sunucudaysa gerekir; o zaman portu güvenlik duvarıyla kısıtlayın. - İzinler: Sahipliği
sudo chown -R deploy:deploy /srv/appile düzeltin. Günlük işlerdesudo pm2 ...çalıştırmayın: Bu, root olarak/root/.pm2altında kendi süreç listesi olan ikinci bir PM2 başlatır ve ikisi aynı port için çakışır.
502 hatasını adım adım çözmek için 502 Bad Gateway hatası rehberimize bakın.
Next.js, Nuxt ve NestJS hakkında bir not
Derleme adımı olan çatılar da aynı şekilde çalışır: npm run build komutunu çalıştırın, ardından script değerini derlenmiş sunucuya yönlendirin. Bu dosya NestJS için dist/main.js, Nuxt için .output/server/index.mjs dosyasıdır (HOST ve PORT değişkenlerini okur); Next.js için ise node_modules/next/dist/bin/next yolunu args: 'start -H 127.0.0.1 -p 3000' ile birlikte kullanın. Kısa yol olan pm2 start npm --name app -- start komutu package.json içindeki start betiğini çalıştırır; ancak PM2 bu durumda uygulamanızı değil npm'i yönettiği için cluster moduna uygun değildir. Nginx ve HTTPS tarafı aynı kalır.
Node.js uygulamaları için Nodesty sunucuları
Nodesty AMD Ryzen 9 9950X VDS paketleri, kodunuzu süreç başına tek çekirdekte çalıştıran Node.js'e yüksek tek çekirdek hızıyla düşük cevap süresi sağlar; AMD EPYC 7763 VDS paketleri ise PM2 cluster modu, veritabanı ve arka plan işlerini aynı sunucuda çalıştırmak için bol çekirdek ve RAM sunar. Tam root erişimi, NVMe disk, nShield DDoS koruması ve 7 gün saklanan ücretsiz günlük yedeklemeyle Express, NestJS ya da Next.js projelerinizi güvenle yayına alabilirsiniz.
Sıkça Sorulan Sorular
Sunucuda neden doğrudan node server.js ya da npm start çalıştırmıyorum?
Elle başlatılan bir süreç SSH oturumunu kapattığınızda durur, çöktüğünde kapalı kalır ve sunucu yeniden başladığında geri gelmez. PM2 gibi bir süreç yöneticisi uygulamayı arka planda çalıştırır, çökünce yeniden başlatır, günlüklerini toplar ve sunucu açıldığında uygulamayı tekrar ayağa kaldırır.
Node.js uygulaması için PM2 mi systemd mi kullanmalıyım?
İkisi de uygulamayı ayakta tutar ve açılışta başlatır. PM2, cluster modu, kesintisiz reload ve kendi günlük görünümü gibi Node.js'e özel kolaylıklar ekler. systemd ise sistemin zaten bir parçasıdır ve her dilde aynı şekilde çalışır. PM2 de açılışta başlamak için küçük bir systemd servisi kullanır.
Node.js uygulamasının önüne Nginx koymam gerekir mi?
Node.js HTTP isteklerine tek başına cevap verebilir; ancak öndeki Nginx 80 ve 443 portlarını, HTTPS sertifikalarını, aynı sunucudaki birden fazla siteyi, yükleme sınırlarını ve yavaş istemcileri üstlenir. Uygulamanız da normal bir kullanıcıyla 3000 gibi yerel bir portta çalışır ve internete doğrudan açılmaz.
pm2 restart ile pm2 reload arasındaki fark nedir?
pm2 restart uygulamanın tüm süreçlerini durdurup yeniden başlatır; bu kısa bir kesintiye yol açar. pm2 reload ise cluster modunda süreçleri tek tek yeniler, böylece isteklere cevap veren bir süreç her zaman bulunur. Tek süreçli fork modunda reload, restart gibi davranır.
Cluster modunda kaç süreç çalıştırmalıyım?
İyi bir başlangıç noktası CPU çekirdeği başına bir süreçtir; max ayarı tam olarak bunu yapar. Her biri kendi belleği olan ayrı bir süreçtir; bu yüzden RAM kullanımını izleyin ve sunucu swap kullanmaya başlarsa sayıyı düşürün. Uygulama, oturumları ya da paylaşılan başka verileri süreç belleğinde tutmamalıdır.
Sitem neden 502 Bad Gateway hatası veriyor?
Nginx, Node.js uygulamasına ulaşamıyor demektir. Ya uygulama çalışmıyordur, ya açılırken sürekli çöküyordur ya da proxy_pass satırındakinden farklı bir portu dinliyordur. Önce pm2 status ve pm2 logs çıktısına, ardından /var/log/nginx/error.log dosyasındaki Nginx hata günlüğüne bakın.
Yazar hakkında
Nodesty Ekibi · Altyapı ve Destek
Nodesty ekibi sunucularımızı, ağımızı ve DDoS korumamızı her gün işletir ve müşteri destek taleplerini 7/24 yanıtlar. Bu rehberler o deneyimden yazılır.
İlgili yazılar

LEMP Kurulumu: Nginx, MariaDB ve PHP-FPM Rehberi
LEMP kurulumu nasıl yapılır? Ubuntu ve Debian'da Nginx, MariaDB ve PHP-FPM kurulumu, server block, PHP soketi, dosya izinleri, HTTPS ve sık hatalar.

tmux Kullanımı: SSH Kapansa da Programlarınız Çalışsın
tmux kullanımı: SSH kapansa da programları çalışır tutma, oturumdan ayrılıp geri dönme, pencere ve bölmeler, kaydırma, .tmux.conf ve sık görülen hatalar.

MySQL Yedek Alma ve Geri Yükleme: mysqldump Rehberi
MySQL ve MariaDB yedek alma: mysqldump ve mariadb-dump, gzip, ~/.my.cnf, büyük içe aktarmalar, cron ile günlük yedek, Docker ve geri yükleme testi.