Node.js Kurulumu (nvm ile Sürüm Yönetimi)

Bir Linux sunucusuna Node.js kurmanın en hızlı yolu apt install nodejs yazmakmış gibi görünür, ama bu yol sizi kısa sürede bir çıkmaza sokar. Dağıtımların depolarındaki Node sürümü genellikle aylarca, bazen yıllarca eskidir; bir projeniz Node 20 isterken bir diğeri Node 18 ile çalışıyorsa aynı makinede ikisini birden barındırmanın kolay bir yolu yoktur; üstelik global paket kurmak için sürekli sudo kullanmak zorunda kalırsınız ki bu da hem güvenlik hem de izin karmaşası demektir. Sistem paket yöneticisi, işletim sisteminin kendi araçları için uygundur; uygulama çalışma zamanlarını yönetmek için tasarlanmamıştır.

Bu rehberde, kıdemli bir sistem yöneticisinin bir müşteri sunucusunu kurarken izlediği yolu adım adım anlatıyoruz. Node Version Manager (nvm) ile Node.js kurmayı, aynı makinede birden çok sürümü yan yana tutmayı, varsayılan sürümü belirlemeyi, npm ile global ve yerel paketleri sağlıklı biçimde yönetmeyi ve en önemlisi bir uygulamayı geliştirme ortamından çıkarıp üretimde PM2 veya systemd ile 7/24 ayakta tutmaya kadar olan köprüyü göreceksiniz. Komutların hepsi gerçek; kendi VDS veya sanal sunucunuzda birebir uygulayabilirsiniz.

apt paketi yerine neden nvm?#

Sistem paket yöneticisiyle Node kurmanın temel sorunu tek sürüme mahkûm olmanızdır. apt, yum veya dnf bir makinede aynı anda yalnızca bir nodejs paketini tutar. Farklı projelerin farklı sürüm gereksinimi olduğunda ya sürekli kaldırıp yeniden kurarsınız ya da hepsini tek sürüme uydurmaya çalışırsınız. Gerçek dünyada bu mümkün değildir; eski bir müşteri projesi Node 18'de, yeni geliştirilen bir servis Node 22'de çalışabilir.

nvm bu sorunu her sürümü ayrı bir dizine kurup PATH değişkenini anlık olarak değiştirerek çözer. Böylece nvm use 20 ile bir terminalde Node 20'ye, başka bir oturumda Node 18'e geçebilirsiniz. Ayrıca nvm kurulumu tamamen kullanıcının kendi ev dizininde (~/.nvm) yaşar; sudo gerektirmez. Bu, global npm paketlerini kurarken izin hatalarıyla boğuşmanızı da bitirir. Aşağıdaki tablo iki yaklaşımı özetliyor.

Tek istisna, çok minimal bir konteyner imajı hazırlıyorsanız resmi Node imajını (node:20-alpine) kullanmanın daha derli toplu olabileceğidir; konteynerlerle çalışmaya yeni başlıyorsanız Docker temelleri rehberimize göz atın. Ama çıplak bir sunucuda veya paylaşımlı bir ortamda nvm neredeyse her zaman doğru tercihtir.

nvm Kurulumu#

nvm'i kurmak tek satırlık bir betikle başlar. Resmi kurulum betiği ~/.nvm dizinini oluşturur ve kabuk profil dosyanıza (~/.bashrc veya ~/.zshrc) gerekli satırları ekler. Önce sisteminizde curl ve git bulunduğundan emin olun; sürüm kontrol araçlarına aşina değilseniz Git temelleri yazımız iyi bir başlangıçtır.

# curl ve git yoksa kur (Debian/Ubuntu)
sudo apt update && sudo apt install -y curl git

# nvm kurulum betigini calistir
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Betik çalıştıktan sonra profilinize şu bloğun eklendiğini göreceksiniz. Eğer otomatik eklenmediyse elle ekleyip kabuğu yeniden yükleyin:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Değişikliğin devreye girmesi için ya yeni bir SSH oturumu açın ya da mevcut oturumda profilinizi yeniden okutun:

source ~/.bashrc     # zsh kullaniyorsaniz: source ~/.zshrc

Artık nvm komutu kullanılabilir olmalı. Doğrulamak için sürümünü sorun:

nvm --version
# ornek cikti: 0.40.1

Eğer command not found: nvm görüyorsanız neredeyse her zaman sorun profil dosyasındaki bloğun okunmamasıdır. Doğru profil dosyasını (login shell için ~/.bash_profile, interaktif shell için ~/.bashrc) düzenlediğinizden emin olun. Bir uzak sunucuda çalışıyorsanız oturumu tamamen kapatıp yeniden bağlanmak en temiz yöntemdir.

Node.js Sürümlerini Kurmak ve Yönetmek#

nvm kurulduktan sonra Node kurmak tek komuttur. En güncel LTS (uzun dönem destekli) sürümü kurmak için:

nvm install --lts

Belirli bir sürümü kurmak isterseniz sürüm numarasını verirsiniz. nvm, ana sürümü verdiğinizde o serideki en yeni yamayı seçer:

nvm install 20        # 20 serisinin en guncel yamasi
nvm install 18.19.1   # tam olarak bu yama
nvm install node      # en yeni "current" surum

Kurulu tüm sürümleri listelemek ve hangisinin aktif olduğunu görmek için:

nvm ls
#   v18.20.4
# -> v20.17.0
#    lts/iron -> v20.17.0
#    default -> lts/*

-> işareti o an aktif olan sürümü gösterir. Bir sürüme geçmek için nvm use kullanılır. Bu değişiklik yalnızca içinde bulunduğunuz kabuk oturumu için geçerlidir; başka bir terminal etkilenmez.

nvm use 18
node -v      # v18.20.4
nvm use 20
node -v      # v20.17.0

En kritik ayar varsayılan sürümü belirlemektir. Yeni açtığınız her terminalin hangi Node'la başlayacağını alias default ile sabitlersiniz. Aksi halde her oturumda elle nvm use yazmak zorunda kalırsınız ki bu üretim ortamında ciddi hatalara yol açar.

# Belirli bir surumu varsayilan yap
nvm alias default 20

# Ya da her zaman en guncel LTS olsun
nvm alias default 'lts/*'

Bir projede hangi Node sürümünün kullanılacağını takım arkadaşlarınızla veya gelecekteki kendinizle paylaşmak için proje kök dizinine bir .nvmrc dosyası koyabilirsiniz. Dosyanın içinde sadece sürüm etiketi bulunur:

echo "20" > .nvmrc
# Sonra o dizinde tek komutla dogru surume gecin:
nvm use

Bir sürüme artık ihtiyacınız kalmadıysa temizlemek de kolaydır. Yalnızca aktif olmayan sürümler kaldırılabilir:

nvm uninstall 18.20.4

LTS mi, Current mı? Üretim İçin Doğru Sürüm#

Node.js iki yayın hattı sürer ve bu ayrımı bilmemek üretimde en sık yapılan hatadır. Current hattı en yeni özellikleri taşır ama kısa ömürlüdür ve kararlılığı LTS kadar sınanmamıştır. LTS hattı ise 30 ay boyunca güvenlik yaması ve bakım alır; üretim sunucuları için tek doğru tercih budur. Node'un çift numaralı ana sürümleri (18, 20, 22) LTS'e terfi eder; tek numaralı sürümler (19, 21, 23) yalnızca geçici Current sürümleridir ve üretimde kullanılmamalıdır.

Aşağıdaki tablo, karar verirken bakmanız gereken pratik ölçütleri özetliyor.

Pratik kural nettir. Bir müşteri projesini veya kendi uygulamanızı canlıya alacaksanız en güncel LTS'i seçin ve bir ana sürümü, EOL (kullanım ömrü sonu) tarihine yaklaşmadan bir üst LTS'e taşımayı planlayın. Bir sürümün ne zaman destekten düşeceğini nvm ls-remote --lts çıktısında ve resmi yayın takviminde görebilirsiniz. Kurumsal iş yüklerini barındırdığımız VDS sunucularımızda standart olarak güncel LTS'i öneriyor, isterseniz sunucu yönetim hizmetimiz kapsamında sürüm geçişlerini de üstleniyoruz.

npm ve Global Paketler#

nvm ile kurduğunuz her Node sürümü kendi npm'iyle birlikte gelir. Bu, npm'i ayrıca kurmanıza gerek kalmadığı anlamına gelir; üstelik global paketler artık sudo gerektirmez, çünkü hepsi ~/.nvm altındaki sürüm dizinine yazılır. Sürümünüzü ve npm'i doğrulamak için:

node -v && npm -v
# v20.17.0
# 10.8.2

Bir projede bağımlılıkları kurmanın iki yolu vardır. Yerel kurulum paketleri projenin node_modules dizinine yazar ve package.json dosyanıza kaydeder; üretim için doğru olan budur. Global kurulum ise komut satırı araçlarını (CLI) sistem genelinde erişilebilir yapar.

# Yerel bagimlilik (projeye kaydedilir)
npm install express

# Sadece uretim bagimliliklarini kur (CI ve sunucu icin)
npm ci --omit=dev

# Global CLI araci ( or. pm2, http hizmetleri)
npm install -g pm2

Burada üretim için kritik bir ayrıntı var. Sunucuda dağıtım yaparken npm install yerine npm ci kullanın. npm ci, package-lock.json dosyasını birebir uygular; node_modules dizinini sıfırdan kurar ve lock dosyasıyla package.json uyuşmuyorsa hata verir. Böylece geliştirme makinesinde çalışan sürümlerin aynısı sunucuda kurulur; "bende çalışıyordu" sorununun büyük kısmı buradan çözülür.

Global paketleri güncel tutmak ve neyin kurulu olduğunu görmek için:

npm ls -g --depth=0      # global kurulu paketler
npm outdated             # projede eski bagimliliklar
npm update               # semver araligindaki guncellemeler

Bir güvenlik notu: npm audit çıktısını ciddiye alın ama körlemesine npm audit fix --force çalıştırmayın; --force bazen ana sürüm atlayarak uygulamanızı bozabilir. Önce raporu okuyun, sonra hedefli güncelleyin. Bağımlılık güvenliği, sunucu güvenliğinin ayrılmaz bir parçasıdır; genel güvenlik katmanları için WAF ve DDoS koruma çözümlerimiz uygulama katmanının üstünü kapatır.

Üretimde Node.js Çalıştırmak — PM2 ve systemd#

Bir uygulamayı node app.js diye başlatmak yalnızca geliştirme için yeterlidir. SSH oturumunuz kapandığında süreç ölür, çökerse kimse yeniden başlatmaz ve sunucu yeniden başladığında uygulama gelmez. Üretimde bir süreç yöneticisine ihtiyacınız var. İki yaygın yol vardır: nvm dünyasına en yakın olan PM2 ve işletim sisteminin yerleşik çözümü systemd.

PM2, Node için tasarlanmış bir süreç yöneticisidir; çökme sonrası otomatik yeniden başlatma, log yönetimi ve çok çekirdekli cluster modu sunar. Kurulum ve temel kullanımı şöyledir:

npm install -g pm2

# Uygulamayi baslat ve isim ver
pm2 start app.js --name api

# Tum cekirdekleri kullan (cluster mod)
pm2 start app.js -i max --name api

# Durum, log ve yeniden baslatma
pm2 status
pm2 logs api
pm2 restart api

# Sunucu yeniden baslayinca PM2'nin otomatik acilmasi
pm2 startup
pm2 save

pm2 startup komutu size çalıştırmanız gereken tek bir sudo satırı verir; onu çalıştırdıktan sonra pm2 save ile mevcut süreç listesini dondurursunuz. Böylece sunucu reboot olduğunda uygulamalarınız otomatik geri gelir.

Alternatif olarak systemd ile de çalışabilirsiniz; bu, ek bir araç kurmadan işletim sisteminin denetim mekanizmasını kullanmak isteyenler için daha "temiz" bir yoldur. Ancak nvm ile kurulu Node systemd'nin gördüğü PATH içinde olmadığından, servis dosyasında node ikilisinin tam yolunu vermeniz gerekir. Yolu which node ile öğrenin.

which node
# /home/deploy/.nvm/versions/node/v20.17.0/bin/node

Ardından bir servis birimi tanımlarsınız:

[Unit]
Description=Node API servisi
After=network.target

[Service]
Type=simple
User=deploy
WorkingDirectory=/home/deploy/api
ExecStart=/home/deploy/.nvm/versions/node/v20.17.0/bin/node server.js
Restart=on-failure
Environment=NODE_ENV=production
Environment=PORT=3000

[Install]
WantedBy=multi-user.target

Bu dosyayı /etc/systemd/system/api.service olarak kaydedip devreye alırsınız:

sudo systemctl daemon-reload
sudo systemctl enable --now api
sudo systemctl status api

Uygulamanız hangi süreç yöneticisiyle çalışırsa çalışsın, doğrudan internete açık bir portta dinlemesini önermiyoruz. Önüne Nginx gibi bir ters vekil (reverse proxy) koyup TLS sonlandırmasını orada yapın:

server {
    listen 443 ssl;
    server_name uygulama.example.com;

    ssl_certificate     /etc/letsencrypt/live/uygulama.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/uygulama.example.com/privkey.pem;

    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;
    }
}

Sertifikayı ücretsiz Let's Encrypt ile alabilir, kurumsal projelerde ise ek güven işaretleri için ücretli SSL çözümlerimizden yararlanabilirsiniz. Ters vekilin arkasında çalışan bir Node uygulaması, hem güvenlik hem de performans açısından çok daha sağlıklıdır.

Sık Karşılaşılan Sorunlar ve Hızlı Çözümler#

Kurulum ve dağıtım sırasında en çok karşılaşılan durumları burada topladık; birçoğunu daha oluşmadan önleyebilirsiniz. En yaygın hata, nvm komutunun yeni SSH oturumunda bulunamamasıdır; bu neredeyse her zaman profil dosyasının okunmamasından kaynaklanır ve doğru profili düzenleyip oturumu yenilemekle çözülür.

İkinci sık sorun, cron veya CI gibi interaktif olmayan kabuklarda nvm'in yüklenmemesidir. Bu ortamlar ~/.bashrc dosyasını okumaz. Çözüm, betiğinizin başında nvm'i elle kaynak göstermek ya da doğrudan sürümün tam yolunu kullanmaktır:

# Cron betiginin basinda
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
nvm use 20 --silent

Bir diğer nokta, sunucu belleğinin npm install sırasında yetersiz kalmasıdır; küçük planlı sanal sunucularda node-gyp gibi derleme adımları belleği tüketebilir. Bu durumda bir swap alanı açmak veya build adımını daha güçlü bir makinede yapıp çıktıyı kopyalamak işe yarar. Kaynak ihtiyacınız büyüdüyse sanal sunucu paketlerimiz arasından daha yüksek RAM'li bir plana geçebilirsiniz. Son olarak, farklı Node sürümleri arasında node_modules paylaşmayın; sürüm değiştirdikten sonra rm -rf node_modules && npm ci ile temiz bir kurulum yapın, çünkü derlenmiş yerel modüller sürüme bağımlıdır.

Sıkça Sorulan Sorular#

nvm ile kurulan Node.js tüm kullanıcılar için mi geçerli?#

Hayır, nvm kurulumu tamamen o kullanıcının ev dizininde (~/.nvm) yaşar ve yalnızca o kullanıcı için geçerlidir. Sunucuda birden fazla kullanıcı Node çalıştıracaksa her biri kendi nvm kurulumunu yapmalıdır. Sistem genelinde tek bir Node kurulumu istiyorsanız resmi NodeSource deposu daha uygun olabilir, ama çoğu senaryoda uygulamaları kendi kullanıcısı altında izole tutmak daha güvenli ve düzenlidir.

Sunucumu yeniden başlattığımda uygulamam otomatik açılır mı?#

nvm tek başına bunu sağlamaz; nvm yalnızca hangi Node sürümünün kullanılacağını yönetir. Uygulamanızın reboot sonrası ayağa kalkması için bir süreç yöneticisi gerekir. PM2 kullanıyorsanız pm2 startup ve pm2 save komutları bu işi görür; systemd kullanıyorsanız servis birimini systemctl enable ile etkinleştirmeniz gerekir. Bu adımı atlarsanız sunucu her yeniden başladığında uygulamanız kapalı kalır.

Hangi Node.js sürümünü seçmeliyim?#

Üretim için her zaman en güncel LTS sürümünü seçin; şu an bu genellikle çift numaralı en yeni ana sürümdür. LTS sürümler yaklaşık 30 ay boyunca güvenlik yaması aldığı için müşteri projelerinde ve canlı sistemlerde tek doğru tercih budur. Tek numaralı Current sürümleri yalnızca yeni özellikleri denemek için yerelde kullanın, üretime almayın.

npm paketlerini kurarken neden artık sudo gerekmiyor?#

Çünkü nvm, Node ve npm'i sistem dizinlerine değil kullanıcınızın ev dizinindeki ~/.nvm altına kurar. Global paketler de bu dizine yazıldığı için root izni gerekmez ve sudo npm install -g alışkanlığından kaynaklanan EACCES izin hatalarıyla bir daha uğraşmazsınız. Bu, hem güvenlik açısından daha iyidir hem de dosya sahipliği karmaşasını ortadan kaldırır.

nvm ile Docker konteynerinde Node kullanmalı mıyım?#

Genellikle hayır. Konteyner ortamında zaten yalıtılmış bir işletim sistemi katmanınız olduğu için resmi node:20 gibi bir temel imaj kullanmak daha sade ve öngörülebilirdir; nvm katmanı gereksiz bir karmaşıklık ekler. nvm asıl gücünü, aynı makinede birden çok proje ve sürümü yönettiğiniz çıplak sunucularda gösterir. Konteyner ve imaj mantığına yeni başlıyorsanız Docker temelleri rehberimiz iyi bir çıkış noktasıdır.

İki farklı projede farklı Node sürümlerini nasıl çalıştırırım?#

Her projenin kök dizinine bir .nvmrc dosyası koyup içine sürüm etiketini yazın, sonra o dizine girdiğinizde nvm use komutunu çalıştırın; nvm otomatik olarak doğru sürüme geçer. Üretimde PM2 veya systemd ile çalıştırıyorsanız her uygulama zaten kendi başlatma komutunda ilgili Node ikilisinin tam yolunu kullandığı için sürümler birbirine karışmaz. Böylece Node 18 isteyen eski bir servisle Node 22 isteyen yeni bir servisi aynı sunucuda sorunsuzca barındırabilirsiniz.

Kapanış#

nvm, bir sunucuda Node.js'i yönetmenin en esnek ve en az sürprizli yoludur. Doğru kurulum, alias default ile sabitlenmiş bir varsayılan sürüm, üretim için LTS tercihi ve PM2 ya da systemd ile kalıcı bir çalıştırma kurgusu bir araya geldiğinde, uygulamanız geliştirme makinenizde nasıl davranıyorsa canlıda da aynı biçimde davranır. Bundan sonrası, önüne bir ters vekil koyup TLS ile güvence altına almak ve düzenli yedek almaktan ibarettir.

Node uygulamanızı sağlam bir altyapıda çalıştırmak istiyorsanız, tam kök erişimi sunan VDS ve sanal sunucu paketlerimiz nvm ile mükemmel uyumludur; kurulum, sürüm geçişi ve süreç yönetimini sizin yerinize üstlenmemizi isterseniz sunucu yönetim hizmetimize göz atın. Hazır uygulamaları tek tıkla kurmak isteyenler için App Center, altyapınızı güçlendirmek için WAF ve DDoS koruma çözümlerimiz de bir tık uzağınızda. Sorularınız için ekibimiz her zaman yanınızda.