Ubuntu ve Debian’a Node.js LTS Kurulumu

Yazar:komut.io ekibi Node.js ve npm Kurulumu
0 Yorum

Node.js kurmak kulağa basit gelir, ama “apt install nodejs” diye geçiştirirseniz kendinizi aylarca eski bir sürümle, kırık npm paketiyle ve “neden çalışmıyor ki” sorusuyla boğuşurken bulabilirsiniz. Ubuntu ve Debian depolarında gelen Node.js sürümleri çoğu zaman gerçek dünya projelerinin ihtiyacını karşılamaz. Bu yazıda doğru yöntemlerle, production-ready bir Node.js LTS kurulumunun nasıl yapılacağını adım adım anlatacağım.

Neden Sistem Deposundaki Node.js Yetmez?

Ubuntu 22.04’ün varsayılan deposuna bakarsanız Node.js 12.x görebilirsiniz. Debian Bullseye’da da durum pek farklı değildir. Oysa bu yazıyı yazdığım sırada Node.js LTS sürümü 20.x bandındaydı. Aradaki fark sadece özellikler değil, güvenlik yamaları, performans iyileştirmeleri ve modern npm sürümü anlamına geliyor.

Birkaç senaryo düşünelim:

  • Bir React veya Next.js projesi üzerinde çalışıyorsunuz, minimum Node.js 18 istiyor
  • Express.js uygulamanızda async/await ile gelen yeni özelliklerden faydalanmak istiyorsunuz
  • CI/CD pipeline’ınızda test koşuyorsunuz ve production ile geliştirme ortamı arasında sürüm uyumsuzluğu var
  • Birden fazla projeyi aynı sunucuda host ediyorsunuz, her biri farklı Node.js sürümü istiyor

Bu senaryoların hepsine uygun cevaplar var. Hepsini tek tek ele alacağız.

Yöntem 1: NodeSource Deposu ile Kurulum (Önerilen)

NodeSource, Node.js’in resmi olarak önerdiği dağıtım kanalıdır. Güncel LTS ve Current sürümlerini her zaman takip eder. Hem Ubuntu hem Debian için aynı adımlar geçerlidir.

Ön Hazırlık

Önce sistemi güncelleyelim ve gerekli bağımlılıkları kuralım:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl gnupg2 ca-certificates lsb-release

NodeSource Kurulum Scripti

NodeSource, kurulumu kolaylaştırmak için bir setup scripti sunuyor. Bu script sisteminize uygun depoyu ekler ve gerekli GPG anahtarını yükler:

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

Buradaki setup_20.x kısmını ihtiyacınıza göre değiştirebilirsiniz. Eğer Node.js 18 LTS istiyorsanız setup_18.x kullanırsınız. Script çalıştıktan sonra NodeSource deposu /etc/apt/sources.list.d/nodesource.list dosyasına eklenmiş olur.

Script ne yapar diye merak ediyorsanız, şu komutla inceleyebilirsiniz:

curl -fsSL https://deb.nodesource.com/setup_20.x -o nodesource_setup.sh
cat nodesource_setup.sh

İçeriğine bakıp güvendiğinizden emin olduktan sonra çalıştırmanızı öneririm. “Pipe to bash” yöntemi hızlıdır ama üretim ortamlarında önce incelemek iyi alışkanlık.

Node.js Kurulumu

Depo eklendikten sonra kurulum standart apt komutuyla yapılır:

sudo apt install -y nodejs

Bu komut hem Node.js’i hem de npm’i kurar. Kurulumu doğrulayalım:

node --version
npm --version

Çıktı şuna benzer olmalı:

v20.11.0
10.2.4

Build Tools Kurulumu

Birçok npm paketi native C++ addon’ları derlemek zorundadır. bcrypt, sharp, canvas gibi paketler bunların başında gelir. Bu yüzden build araçlarını da kurmak gerekir:

sudo apt install -y build-essential

Alternatif olarak npm üzerinden de kurabilirsiniz:

sudo npm install -g node-gyp

Yöntem 2: NVM ile Kurulum (Geliştirici Ortamları İçin)

NVM (Node Version Manager), özellikle geliştirici makinelerinde ve birden fazla Node.js sürümü gereken sunucularda altın değerindedir. Sistem genelinde değil, kullanıcı bazında çalışır, yani sudo gerektirmez.

NVM Kurulumu

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

Script çalıştıktan sonra shell’inizi yeniden başlatmanız ya da aşağıdaki komutu çalıştırmanız gerekir:

source ~/.bashrc
# Zsh kullanıyorsanız:
source ~/.zshrc

NVM’in başarıyla kurulduğunu doğrulayalım:

nvm --version

NVM ile Node.js LTS Kurulumu

# En güncel LTS sürümünü kur
nvm install --lts

# Belirli bir sürüm kurmak isterseniz
nvm install 20.11.0

# Mevcut LTS sürümünü aktif et
nvm use --lts

# Varsayılan sürümü ayarla
nvm alias default 20.11.0

NVM’in güzel yanı birden fazla sürümü yan yana tutabilmesidir:

# Farklı sürümler kur
nvm install 18.19.0
nvm install 20.11.0

# Sürümler arasında geç
nvm use 18.19.0
node --version  # v18.19.0

nvm use 20.11.0
node --version  # v20.11.0

# Kurulu sürümleri listele
nvm ls

Proje Bazında Sürüm Yönetimi

Proje klasörünüzde .nvmrc dosyası oluşturarak projeye özel Node.js sürümünü belirtebilirsiniz:

echo "20.11.0" > .nvmrc

Artık bu klasöre girdiğinizde nvm use komutunu çalıştırmak yeterli. Otomatik geçiş için .bashrc dosyanıza şunu ekleyebilirsiniz:

# .bashrc veya .zshrc sonuna ekleyin
autoload -U add-zsh-hook
load-nvmrc() {
  local nvmrc_path="$(nvm_find_nvmrc)"
  if [ -n "$nvmrc_path" ]; then
    local nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")")
    if [ "$nvmrc_node_version" = "N/A" ]; then
      nvm install
    elif [ "$nvmrc_node_version" != "$(nvm version)" ]; then
      nvm use
    fi
  fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc

Yöntem 3: Snap ile Kurulum

Snap, özellikle Ubuntu’da alternatif bir seçenek olarak sunulur. Güvenli sandbox ortamı sağlar ama performans açısından tartışmalı bulunur. Kritik production sunucularında pek tercih etmesem de, pratik senaryolar için işe yarar:

sudo snap install node --classic --channel=20/stable

Sürüm kanallarını listelemek için:

snap info node | grep stable

npm Konfigürasyonu ve Global Paket Yönetimi

Node.js kurduktan sonra npm’i düzgün konfigüre etmek gerekir. En yaygın sorunlardan biri global paketleri sudo ile kurmak zorunda kalmaktır. Bunu düzeltelim.

Global npm Dizinini Değiştirme

NodeSource yöntemiyle kurduyysanız, global paketler için ev dizininde özel bir klasör oluşturmanız önerilir:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

Bu dizini PATH’e ekleyin:

echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Artık global paketleri sudo olmadan kurabilirsiniz:

npm install -g pm2
npm install -g typescript
npm install -g nodemon

npm Registry ve Timeout Ayarları

Türkiye’den npm registry’ye bağlanırken zaman zaman timeout sorunları yaşanabilir. Birkaç faydalı ayar:

# Registry ayarını kontrol et
npm config get registry

# Timeout değerini artır (milisaniye cinsinden)
npm config set fetch-timeout 60000
npm config set fetch-retry-mintimeout 20000
npm config set fetch-retry-maxtimeout 120000

# Mevcut npm konfigürasyonunu görüntüle
npm config list

Production Ortamı İçin pm2 Kurulumu

Node.js uygulamalarını production’da çalıştırmak için process manager şarttır. pm2, bu iş için endüstri standardı haline gelmiştir:

npm install -g pm2

Temel kullanım:

# Uygulamayı başlat
pm2 start app.js --name "my-api"

# Cluster modunda başlat (tüm CPU çekirdeklerini kullan)
pm2 start app.js -i max --name "my-api"

# Sistem başlangıcında otomatik başlat
pm2 startup systemd
pm2 save

# Durum kontrolü
pm2 status
pm2 logs my-api
pm2 monit

pm2 ile ecosystem dosyası oluşturmak, büyük projelerde yönetimi kolaylaştırır:

cat > ecosystem.config.js << 'EOF'
module.exports = {
  apps: [
    {
      name: 'my-api',
      script: './src/index.js',
      instances: 'max',
      exec_mode: 'cluster',
      env: {
        NODE_ENV: 'production',
        PORT: 3000
      },
      max_memory_restart: '500M',
      error_file: '/var/log/my-api/error.log',
      out_file: '/var/log/my-api/out.log',
      log_date_format: 'YYYY-MM-DD HH:mm:ss'
    }
  ]
}
EOF

pm2 start ecosystem.config.js

Gerçek Dünya Senaryosu: CI/CD Pipeline İçin Node.js

Bir GitHub Actions veya GitLab CI pipeline’ında Node.js sürümünü sabitlemek önemlidir. Docker tabanlı bir CI ortamında şu Dockerfile işinizi görecektir:

FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y 
    curl 
    gnupg2 
    ca-certificates 
    build-essential 
    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - 
    && apt-get install -y nodejs 
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

EXPOSE 3000
CMD ["node", "dist/index.js"]

npm install yerine npm ci kullanmak, CI ortamlarında package-lock.json‘a sıkı sıkıya bağlı kalınmasını sağlar ve tekrar üretilebilir build’ler elde edersiniz.

Güvenlik Güncellemeleri ve Sürüm Takibi

LTS Takvimini Takip Etmek

Node.js, çift sayılı major sürümleri LTS olarak belirler ve her Ekim ayında yeni bir LTS sürümü aktif hale gelir. Destek takvimi şu şekilde işler:

  • Active LTS: Yeni özellikler ve güvenlik yamaları alır
  • Maintenance LTS: Sadece kritik güvenlik yamaları alır
  • End-of-Life: Artık güncelleme almaz, kullanmamalısınız

Güvenlik Güncellemelerini Uygulamak

NodeSource deposunu eklediğinizde, Node.js güncellemeleri normal apt güncellemelerine dahil olur:

# Sadece Node.js güncellemelerini kontrol et
apt list --upgradable 2>/dev/null | grep nodejs

# Güncelle
sudo apt update && sudo apt install --only-upgrade nodejs

npm Audit

Projenizdeki güvenlik açıklarını taramak için:

# Güvenlik açığı taraması
npm audit

# Otomatik düzeltme dene
npm audit fix

# Kırılabilir değişiklikler dahil düzelt (dikkatli olun)
npm audit fix --force

Yaygın Hatalar ve Çözümleri

“node: command not found” Hatası

NVM kurulumundan sonra bu hatayla karşılaşıyorsanız büyük ihtimalle shell konfigürasyonu yüklenmemiştir:

# NVM'in yüklenip yüklenmediğini kontrol et
cat ~/.bashrc | grep nvm

# Manuel olarak yükle
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

EACCES Hatası (Global Paket Kurulumu)

Sudo olmadan global paket kurarken izin hatası alıyorsanız:

# npm'in prefix'ini kontrol et
npm config get prefix

# Eğer /usr veya /usr/local gösteriyorsa ev dizinine al
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Eski Node.js Sürümünü Kaldırma

Sistem deposundan kurulu eski bir Node.js varsa önce temizlemeniz gerekir:

# Mevcut kurulumu kontrol et
which node
dpkg -l | grep -i node

# Kaldır
sudo apt remove nodejs npm
sudo apt autoremove

# Kalan konfigürasyonları temizle
sudo apt purge nodejs

# npm cache temizle
rm -rf ~/.npm

Kurulumu Doğrulama ve Test

Her şeyin doğru çalışıp çalışmadığını test etmek için basit bir HTTP sunucusu yazalım:

cat > /tmp/test-server.js << 'EOF'
const http = require('http');
const os = require('os');

const server = http.createServer((req, res) => {
  res.writeHead(200, {'Content-Type': 'application/json'});
  res.end(JSON.stringify({
    nodeVersion: process.version,
    platform: os.platform(),
    hostname: os.hostname(),
    uptime: os.uptime(),
    message: 'Node.js calisiyor!'
  }, null, 2));
});

server.listen(3000, () => {
  console.log(`Sunucu calisiyor: http://localhost:3000`);
  console.log(`Node.js surumu: ${process.version}`);
});
EOF

node /tmp/test-server.js &
sleep 1
curl -s http://localhost:3000 | python3 -m json.tool
kill %1

Bu script çalışıyorsa Node.js kurulumunuz sağlıklıdır.

Sonuç

Ubuntu ve Debian’a Node.js kurmak için en güvenilir yol NodeSource deposunu kullanmaktır. Sunucu ortamları için bu yöntem hem bakımı kolay hem de apt ekosistemiyle entegredir. Geliştirici makinelerinde veya birden fazla Node.js sürümü gereken ortamlarda ise NVM vazgeçilmez bir araçtır.

Hangi yöntemi seçerseniz seçin, şu noktalara dikkat edin:

  • Sistem deposundaki Node.js’i kullanmayın, sürümler çok eski kalıyor
  • Global npm paketleri için sudo kullanmaktan kaçının
  • Production ortamlarında mutlaka pm2 gibi bir process manager kullanın
  • npm audit ile güvenlik taramasını rutininize ekleyin
  • Node.js LTS takvimini takip edin, End-of-Life sürümlerde kalmayın

Bu adımları doğru uyguladığınızda, hem güvenli hem de bakımı kolay bir Node.js ortamına sahip olursunuz. Herhangi bir adımda takılırsanız yorum bırakın, çözmeye çalışalım.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir