Node.js ve PM2’yi Ubuntu’ya Nasıl Kurulur: Eksiksiz Bir Üretim Kılavuzu

Node.js, yüksek verimlilikle sunucu tarafında JavaScript kodu çalıştırmak için tasarlanmış, Chrome’un V8 motoru üzerine inşa edilmiş asenkron, olay güdümlü bir JavaScript çalışma ortamıdır. PM2, daemonlaştırma, otomatik çökme kurtarma, log toplama, cluster modu yük dengeleme ve başlangıç betiği oluşturma özelliklerini — hepsini tek bir CLI arayüzünden — sağlayan, Node.js uygulamaları için üretim kalitesinde bir süreç yöneticisidir.

Bu kılavuz, Node.js uygulamalarını Ubuntu 20.04, 22.04 veya 24.04 LTS üzerinde bir üretim ortamında güvenilir biçimde çalıştırmak için ihtiyaç duyduğunuz tüm kurulum yöntemlerini, yapılandırma seçeneklerini ve operasyonel kalıpları kapsamaktadır.

Ön Koşullar

Devam etmeden önce aşağıdakileri doğrulayın:

• İşletim sistemi: Ubuntu 20.04, 22.04 veya 24.04 LTS (sunucu veya masaüstü)
• Kullanıcı ayrıcalıkları: `sudo` veya root erişimi
• Ağ erişimi: Paket ve betikleri indirmek için giden HTTPS
• curl kurulu: Henüz mevcut değilse `sudo apt install curl -y` komutunu çalıştırın

Bunu bir bulut sunucusunda çalıştırıyorsanız, VPS Hosting ortamı Node.js iş yükleri için en yaygın dağıtım hedefidir ve bu kılavuzdaki her şey doğrudan geçerlidir.

Adım 1: Sistem Paketlerini Güncelleyin

Yeni yazılım kurmadan önce her zaman paket dizininizi senkronize edin ve bekleyen yükseltmeleri uygulayın. Eski paket meta verileri, bağımlılık çakışmalarının sık görülen bir kaynağıdır.

“`bash

sudo apt update

sudo apt upgrade -y

“`

Yükseltme tamamlandıktan sonra, kernel güncellendiyse yeniden başlatın:

“`bash

sudo reboot

“`

Adım 2: Node.js Kurulumu — Doğru Yöntemi Seçmek

Ubuntu’da Node.js için üç temel kurulum yöntemi vardır. Her birinin sürüm kontrolü, izolasyon ve sistem genelinde kullanılabilirlik açısından farklı değiş tokuşları vardır.

Yöntem Karşılaştırması

Yöntem 1: NodeSource Aracılığıyla Node.js Kurulumu (Sunucular için Önerilen)

NodeSource, her aktif Node.js sürüm serisi için güncel Debian/Ubuntu depoları sağlar. Bu, sistem genelinde tek ve kararlı bir sürümün gerektiği üretim sunucuları için tercih edilen yaklaşımdır.

Mevcut LTS sürümü için NodeSource deposunu ekleyin:

“`bash

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash –

“`

Bu betik birkaç işlem gerçekleştirir: Ubuntu sürümünüzü algılar, uygun NodeSource apt deposunu ekler, GPG imzalama anahtarını içe aktarır ve `apt-get update` komutunu çalıştırır. `-E` bayrağı, sudo’ya yükseltirken ortam değişkenlerinizi korur; bu, proxy ayarlarınız yapılandırılmışsa önem taşır.

Node.js ve npm’i kurun:

“`bash

sudo apt install nodejs -y

“`

NodeSource paketi, hem `node` hem de `npm`’yi tek bir `nodejs` paketinde bir araya getirir. Ubuntu universe paketinin aksine, bunları ayırmaz.

Kurulumu doğrulayın:

“`bash

node -v

npm -v

“`

Beklenen çıktı örneği:

“`

v20.14.0

10.7.0

“`

Belirli bir ana sürüme sabitleme: Mevcut LTS yerine Node.js 18’e ihtiyaç duyuyorsanız, curl komutundaki `setup_lts.x`’yi `setup_18.x` ile değiştirin. Mevcut akışlar arasında `setup_18.x`, `setup_20.x` ve `setup_22.x` yer almaktadır.

Yöntem 2: NVM Aracılığıyla Node.js Kurulumu (Geliştirme ve Çok Sürümlü Ortamlar için Önerilen)

NVM (Node Version Manager), Node.js’yi ana dizininize kurar; ne Node.js’nin kendisi ne de global olarak kurulan npm paketleri için root ayrıcalığı gerektirmez. Bu, sistem genelinde kurulu Node.js üzerinde `npm install -g` çalıştırırken sıklıkla ortaya çıkan izin sorunlarını ortadan kaldırır.

NVM’yi kurun:

“`bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

“`

Bu komutu çalıştırmadan önce en son sürüm etiketi için resmi NVM deposunu kontrol edin — URL’deki sürüm numarası her sürümle birlikte değişir.

Shell ortamınızı yeniden yükleyin:

“`bash

source ~/.bashrc

“`

Zsh kullanıyorsanız bunun yerine `~/.zshrc`’yi kaynaklayın. NVM yükleyicisi, başlatma bloğunu algıladığı shell yapılandırma dosyasına ekler.

Node.js’nin en son LTS sürümünü kurun:

“`bash

nvm install –lts

“`

LTS’nin yanına belirli bir sürüm kurun:

“`bash

nvm install 18

nvm install 20

“`

Kurulu sürümler arasında geçiş yapın:

“`bash

nvm use 20

nvm alias default 20

“`

`alias default` komutu, yeni shell oturumlarında etkinleşen sürümü ayarlar; bu, etkileşimli shell profilinizi kaynaklayan betikler ve cron işleri için kritik öneme sahiptir.

Doğrulayın:

“`bash

node -v

npm -v

“`

Üretim için kritik NVM tuzağı: NVM kullanıcı kapsamlı olduğundan, PM2’nin başlangıç betikleri ve systemd birimleri, yolu açıkça yapılandırmadığınız sürece NVM tarafından yönetilen Node.js ikili dosyasına erişemez. Bunu doğru şekilde nasıl ele alacağınız için Adım 5’e bakın.

Adım 3: PM2’yi Kurun

PM2, bir npm paketi olarak dağıtılır ve CLI’sinin sistem genelinde kullanılabilir olması için global olarak kurulmalıdır.

PM2’yi kurun:

“`bash

sudo npm install -g pm2

“`

Node.js’yi NVM aracılığıyla kurduysanız `sudo`’yi atlayın:

“`bash

npm install -g pm2

“`

Kurulumu doğrulayın:

“`bash

pm2 -v

“`

Belirli bir PM2 sürümünü kurun (altyapıyı sabitlerken kullanışlıdır):

“`bash

sudo npm install -g pm2@5.3.1

“`

PM2 sürüm 5.x mevcut kararlı seridir. v4 ile karşılaştırıldığında web panosunda (pm2 plus), log rotasyonunda ve modül sisteminde önemli iyileştirmeler sunmuştur.

Adım 4: PM2 ile Node.js Uygulamalarını Yönetme

Bir Uygulamayı Başlatma

Uygulama dizininize gidin ve başlatın:

“`bash

cd /var/www/my-app

pm2 start app.js –name "my-app"

“`

Her zaman `–name` bayrağı atayın. Aksi takdirde PM2, süreç adı olarak dosya adını kullanır; bu, birden fazla servisiniz olduğunda belirsizleşir.

Ek seçeneklerle başlatma:

“`bash

pm2 start app.js –name "my-app" –watch –max-memory-restart 300M

“`

• `–watch`: Kaynak dosyalar değiştiğinde süreci yeniden başlatır (hazırlık ortamında kullanışlı, üretimde önerilmez)
• `–max-memory-restart 300M`: RSS belleği 300 MB’ı aşarsa süreci otomatik olarak yeniden başlatır — bellek sızıntılarına karşı kritik bir güvence

Çalışan Süreçleri Görüntüleme

“`bash

pm2 list

“`

Bu komut, süreç kimliği, ad, mod (fork/cluster), PID, durum, CPU kullanımı, bellek tüketimi ve yeniden başlatma sayısını gösteren bir tablo çıktısı verir.

Gerçek zamanlı bir pano için:

“`bash

pm2 monit

“`

Süreçleri Kontrol Etme

“`bash

pm2 restart my-app # Graceful restart

pm2 reload my-app # Zero-downtime reload (cluster mode only)

pm2 stop my-app # Stop without removing from process list

pm2 delete my-app # Stop and remove from process list

“`

`restart` ile `reload` arasındaki fark: `restart` süreci sonlandırır ve yeni bir tane başlatır; bu kısa bir kesintiye neden olur. `reload` (yalnızca cluster modunda kullanılabilir) çalışanları tek tek döngüye alır ve bu süre boyunca kullanılabilirliği korur. Üretim cluster dağıtımlarında her zaman `reload` kullanın.

Log Yönetimi

“`bash

pm2 logs # Stream logs from all processes

pm2 logs my-app # Stream logs for a specific process

pm2 logs my-app –lines 200 # Show last 200 lines

pm2 flush # Clear all log files

“`

PM2, logları varsayılan olarak `~/.pm2/logs/` konumunda saklar. Üretim sunucularında disk tükenmesini önlemek için log rotasyon modülünü kurun:

“`bash

pm2 install pm2-logrotate

pm2 set pm2-logrotate:max_size 50M

pm2 set pm2-logrotate:retain 10

pm2 set pm2-logrotate:compress true

“`

Bu, loglar 50 MB’a ulaştığında döndürür, 10 sıkıştırılmış arşivi saklar ve kontrolden çıkan log büyümesini önler — uzun süredir çalışan sunucularda disk alanı tükenmeden sıklıkla gözden kaçan yaygın bir sorundur.

Adım 5: PM2’yi Sistem Önyüklemesinde Başlayacak Şekilde Yapılandırın

PM2’nin sunucu yeniden başlatmalarından sonra da çalışmaya devam etmesi için yapılandırılması gerekir. Bu işlem, PM2’nin kendisi tarafından oluşturulan bir systemd servis birimi aracılığıyla gerçekleştirilir.

Başlangıç komutunu oluşturun:

“`bash

pm2 startup

“`

PM2, init sisteminize ve mevcut kullanıcınıza göre özelleştirilmiş bir komut çıktısı verecektir. Şuna benzer görünür:

“`

[PM2] Init System found: systemd

[PM2] To setup the Startup Script, copy/paste the following command:

sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u ubuntu –hp /home/ubuntu

“`

Bu komutu kopyalayın ve tam olarak çalıştırın. Değiştirmeyin — PM2 ikili dosyasının yolu ve ana dizin, sisteminizin yapılandırmasıyla eşleşmelidir.

NVM’ye özgü başlangıç yapılandırması: Node.js’yi NVM aracılığıyla kurduysanız, oluşturulan komuttaki yol NVM tarafından yönetilen ikili dosyanıza işaret edecektir. Bu doğrudur, ancak `pm2 startup`’yi çalıştırmadan önce NVM sürümünün varsayılan olarak ayarlandığından emin olmalısınız:

“`bash

nvm alias default 20

pm2 startup

“`

Mevcut süreç listesini kaydedin:

“`bash

pm2 save

“`

Bu, süreç listesini `~/.pm2/dump.pm2` konumuna yazar. Yeniden başlatmada, systemd birimi bu dosyayı okur ve kaydedilen tüm süreçleri geri yükler. Daha sonra uygulama ekler veya kaldırırsanız, anlık görüntüyü güncellemek için `pm2 save`’yi tekrar çalıştırın.

systemd biriminin aktif olduğunu doğrulayın:

“`bash

systemctl status pm2-ubuntu

“`

`ubuntu`’yi gerçek kullanıcı adınızla değiştirin.

Adım 6: PM2 Ekosistem Dosyalarıyla Üretim Dağıtımı

Tek betikli bir uygulamanın ötesinde herhangi bir şey için PM2’nin ekosistem yapılandırma dosyasını kullanın. Tekrarlanabilir, sürüm kontrollü süreç tanımları sağlar ve uzun CLI bayraklarını hatırlama ihtiyacını ortadan kaldırır.

Ekosistem Dosyasını Oluşturma

“`bash

pm2 ecosystem

“`

Bu, mevcut dizinde `ecosystem.config.js` oluşturur.

Üretime Hazır Bir Ekosistem Yapılandırması

“`javascript

module.exports = {

apps: [

{

name: 'api-server',

script: './src/server.js',

instances: 'max',

exec_mode: 'cluster',

watch: false,

max_memory_restart: '500M',

log_date_format: 'YYYY-MM-DD HH:mm:ss Z',

error_file: '/var/log/pm2/api-server-error.log',

out_file: '/var/log/pm2/api-server-out.log',

merge_logs: true,

env: {

NODE_ENV: 'development',

PORT: 3000

},

env_production: {

NODE_ENV: 'production',

PORT: 8080

}

},

{

name: 'worker',

script: './src/worker.js',

instances: 2,

exec_mode: 'fork',

cron_restart: '0 2 * * *',

env_production: {

NODE_ENV: 'production'

}

}

]

};

“`

Temel yapılandırma kararlarının açıklaması:

• `instances: 'max'`: PM2, mantıksal CPU çekirdeği başına otomatik olarak bir çalışan oluşturur. 4 çekirdekli bir sunucuda bu, donanımı tam olarak kullanan 4 Node.js süreci oluşturur.
• `exec_mode: 'cluster'`: Node.js’nin yerleşik cluster modülünü kullanır. Tüm örnekler, işletim sisteminin soket yük dengelemesi aracılığıyla aynı portu paylaşır.
• `exec_mode: 'fork'`: Süreci bağımsız bir alt süreç olarak çalıştırır. HTTP sunucusu olmayan uygulamalar için gereklidir (kuyruk çalışanları, zamanlanmış işler, yapışkan oturumlu WebSocket sunucuları).
• `merge_logs: true`: Tüm cluster örneklerinden gelen stdout’u tek bir log dosyasında birleştirir; bu, log analizini önemli ölçüde kolaylaştırır.
• `cron_restart`: Cron sözdizimini kullanarak otomatik yeniden başlatmaları zamanlar. Durum biriktiren çalışanlar veya gecelik yapılandırma değişikliklerini uygulamak için kullanışlıdır.

Ekosistem Dosyasıyla Başlatma

“`bash

pm2 start ecosystem.config.js –env production

pm2 save

“`

Sıfır Kesintili Dağıtım İş Akışı

Uygulamanızın yeni bir sürümünü dağıtırken:

“`bash

git pull origin main

npm install –production

pm2 reload ecosystem.config.js –env production

“`

`pm2 reload`, her çalışana tek tek `SIGINT` gönderir, yeni çalışanın hazır olmasını bekler, ardından eskisini sonlandırır. Bunun doğru çalışması için uygulamanızın `SIGINT`’yi zarif biçimde işlemesi ve `process.send('ready')` kullanarak hazırlığı bildirmesi gerekir.

Uygulamanızdaki zarif kapatma işleyicisi:

“`javascript

process.on('SIGINT', () => {

server.close(() => {

console.log('HTTP server closed');

process.exit(0);

});

});

“`

Adım 7: PM2 İzleme ve Gözlemlenebilirlik

Yerleşik İzleme

“`bash

pm2 monit

“`

Terminalde her süreç için gerçek zamanlı CPU ve bellek grafikleri görüntüler.

Süreç Bilgisi

“`bash

pm2 show my-app

“`

Ayrıntılı meta verileri çıktılar: çalışma süresi, yeniden başlatma sayısı, sürüm bilgisi, yorumlayıcı yolu, ortam değişkenleri ve log dosyası konumları.

PM2 Web Panosu (PM2 Plus)

PM2, pm2.io adresinde barındırılan bir izleme panosu sunar. Sunucunuzu bağlayın:

“`bash

pm2 link <secret_key> <public_key>

“`

Bu, geçmiş metrikler, uyarı verme ve uzaktan süreç yönetimi sağlar — özellikle birden fazla sunucuyu yönetirken veya SSH erişimi olmadan görünürlüğe ihtiyaç duyduğunuzda değerlidir.

Adım 8: Node.js ve PM2’yi Güncelleme

PM2’yi Güncelleme

“`bash

sudo npm install -g pm2@latest

pm2 update

“`

`pm2 update`, PM2 ikili dosyasını yükselttikten sonra çalışan süreçleri kesintiye uğratmadan bellekteki PM2 daemon’ını güncellemek için zorunludur.

NodeSource Aracılığıyla Node.js’yi Güncelleme

Yeni ana sürüm için kurulum betiğini yeniden çalıştırın:

“`bash

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash –

sudo apt install nodejs -y

“`

Node.js’yi güncelledikten sonra, yeni ikili dosyayı kullandığından emin olmak için PM2’yi yeniden başlatın:

“`bash

pm2 restart all

“`

NVM Aracılığıyla Node.js’yi Güncelleme

“`bash

nvm install 22

nvm alias default 22

nvm use 22

pm2 restart all

“`

Varsayılan NVM sürümünü değiştirdiyseniz, systemd birimindeki ikili yolu güncellemek için PM2 başlangıç betiğini yeniden oluşturun:

“`bash

pm2 unstartup

pm2 startup

pm2 save

“`

Güvenlik Sertleştirme Değerlendirmeleri

Node.js uygulamalarını üretimde çalıştırmak, süreç yönetiminin ötesinde dikkat gerektirir:

• Root olmayan kullanıcı olarak çalıştırın: PM2 veya Node.js’yi hiçbir zaman root olarak çalıştırmayın. Özel bir sistem kullanıcısı oluşturun (`adduser –system –group nodeapp`) ve PM2’yi bu hesap altında çalıştırın.
• Ortam değişkeni yönetimi: Gizli bilgileri `ecosystem.config.js`’ye sabit kodlamayın. `dotenv` aracılığıyla yüklenen bir `.env` dosyası kullanın veya gizli bilgileri dağıtım hattınız aracılığıyla enjekte edin. Ekosistem dosyası genellikle sürüm kontrolüne işlenir.
• Ters proxy: Node.js uygulamanızın önüne Nginx veya Caddy yerleştirin. Bu, TLS sonlandırma, statik dosya sunumu, hız sınırlama ve istek tamponlamayı yönetir. HTTPS’yi zorunlu kılmak için bunu bir SSL Certificates çözümüyle eşleştirin.
• Güvenlik duvarı kuralları: Node.js portunuza (örn. 3000, 8080) genel internetten doğrudan erişimi engelleyin. Yalnızca ters proxy Node.js ile iletişim kurmalıdır.
• Kaynak sınırları: PM2’de `max_memory_restart` ayarlayın ve tek bir kontrolden çıkmış sürecin sunucuyu istikrarsızlaştırmasını önlemek için sistem düzeyinde `ulimit` değerlerini yapılandırın.

Kaynak izolasyonunun kritik önem taşıdığı yüksek trafikli üretim dağıtımları için, Dedicated Servers ortamı tam donanım kontrolü sağlar ve paylaşılan altyapıya özgü gürültülü komşu sorununu ortadan kaldırır.

Node.js için Doğru Hosting Ortamını Seçme

Teknik Karar Kontrol Listesi

Node.js ve PM2’yi üretime dağıtmadan önce bu kontrol listesini kullanın:

• [ ] Node.js, NodeSource (sunucu) veya NVM (geliştirme) aracılığıyla kuruldu — Ubuntu universe paketi değil
• [ ] PM2, kurulum yönteminiz için doğru izinlerle global olarak kuruldu
• [ ] Uygulama `–name` bayrağı ve tanımlı bir `–max-memory-restart` eşiğiyle başlatıldı
• [ ] HTTP sunucuları için cluster modu etkinleştirildi; arka plan çalışanları için fork modu kullanıldı
• [ ] `pm2 startup` çalıştırıldı ve oluşturulan komut sudo ile çalıştırıldı
• [ ] Tüm süreçler yapılandırıldıktan sonra `pm2 save` çalıştırıldı
• [ ] Log rotasyon modülü kuruldu ve yapılandırıldı
• [ ] Nginx veya Caddy, TLS ile ters proxy olarak yapılandırıldı
• [ ] Uygulama, sıfır kesintili yeniden yüklemeler için `SIGINT`’yi zarif biçimde işliyor
• [ ] Gizli bilgiler `ecosystem.config.js` dışında yönetiliyor
• [ ] PM2 systemd birimi `systemctl status pm2-<username>` ile doğrulandı
• [ ] Güvenlik duvarı, Node.js portlarına genel internetten doğrudan erişimi engelliyor

SSS

PM2 fork modu ile cluster modu arasındaki fark nedir?

Fork modu, uygulamayı tek bir alt süreç olarak başlatır — bir örnek, bir CPU çekirdeği kullanılır. Cluster modu, Node.js’nin yerel cluster modülünü kullanarak aynı TCP portunu paylaşan birden fazla çalışan süreci oluşturur; bu, gerçek çok çekirdekli kullanım ve sıfır kesintili yeniden yükleme sağlar. HTTP/HTTPS sunucuları için cluster modunu, çalışanlar, cron işleri veya çok süreçli paylaşımla uyumsuz dahili durum koruyan uygulamalar için fork modunu kullanın.

`pm2 startup`’yi çalıştırmama rağmen PM2 neden sunucu yeniden başlatmasından sonra başlamıyor?

En yaygın neden, süreçler yapılandırıldıktan sonra `pm2 save`’nin çalıştırılmamış olmasıdır; bu nedenle döküm dosyası boş veya eksiktir. İkinci en yaygın neden, NVM yolu uyuşmazlığıdır: başlangıç betiği oluşturulduktan sonra NVM varsayılan sürümü değiştirildiyse, systemd birimi var olmayan bir ikili dosyaya işaret eder. Bunu çözmek için `pm2 unstartup`’yi çalıştırın, doğru NVM varsayılanını ayarlayın, ardından `pm2 startup` ve `pm2 save`’yi yeniden çalıştırın.

PM2, Node.js dışı süreçleri yönetebilir mi?

Evet. PM2, yorumlayıcıyı belirterek herhangi bir çalıştırılabilir dosyayı yönetebilir. Örneğin: `pm2 start script.py –interpreter python3`. Bu, PM2’yi karma dilli mikro servis mimarileri için genel amaçlı bir süreç denetçisi olarak kullanışlı kılar.

Tek bir sunucunun arkasında farklı portlarda birden fazla Node.js uygulamasını nasıl çalıştırabilirim?

Her uygulamayı `ecosystem.config.js`’de ayrı `PORT` ortam değişkenleriyle ayrı bir giriş olarak tanımlayın. Nginx’i, her porta yönlendiren ayrı `server` blokları veya `location` yönergeleriyle ters proxy olarak yapılandırın. Tüm uygulamalar aynı PM2 daemon’ını paylaşır ve tek bir `pm2 list` görünümü aracılığıyla yönetilir.

Üretim VPS için NVM mi yoksa NodeSource mı kullanmalıyım?

NodeSource, üretim sunucuları için genellikle tercih edilir. Node.js’yi bir sistem paketi olarak kurar; bu, shell başlatma bağımlılıkları olmadan tüm kullanıcılar ve sistem servisleri tarafından kullanılabilir hale getirir. NVM’nin kullanıcı başına, shell başına etkinleştirme modeli, etkileşimli bir shell oturumu dışında çalışan systemd birimlerinde, cron işlerinde ve CI/CD hatlarında ince hata modları ortaya çıkarır. NVM’yi, birden fazla Node.js sürümünü aynı anda yönetmenin gerçek bir gereksinim olduğu yerel geliştirme makineleri için saklayın.