cPanel'de Node.js Uygulaması Çalıştırma

Node.js denince çoğu geliştiricinin aklına doğrudan bir VPS, kendi başına yönettiği bir Linux sunucusu ve terminalde elle çalıştırılan node server.js komutu gelir. Oysa paylaşımlı hosting dünyasında da Node uygulaması yayınlamak yıllardır mümkün; cPanel bunu "Setup Node.js App" (bazı temalarda "Application Manager") aracıyla, arka planda Phusion Passenger uygulama sunucusunu kullanarak yapıyor. Bu sayede Express ile yazdığınız bir API'yi, Next.js benzeri bir SSR uygulamasını ya da küçük bir Node servisini, kendi başınıza systemd servisi yazmadan, portlarla uğraşmadan ve süreç yönetimini elle takip etmeden alan adınızda çalıştırabiliyorsunuz.

Bu rehberde cPanel üzerinde bir Node.js uygulamasını sıfırdan yayına almanın tüm adımlarını anlatacağım: uygulama kök dizinini ve başlangıç dosyasını doğru seçmek, Node sürümünü belirlemek, npm install ile bağımlılıkları kurmak, ortam değişkenlerini tanımlamak, uygulamayı başlatıp yeniden başlatmak ve en önemlisi bir şeyler ters gittiğinde logları okuyup sorunu bulmak. Passenger'ın port yönetimini nasıl soyutladığını, neden kodunuzda sabit port yazmamanız gerektiğini ve reverse proxy mantığının perde arkasında nasıl işlediğini de somut örneklerle göreceğiz. Amacım, bu yazıyı bitirdiğinizde bir müşteriye telefonla anlatır gibi rahatça "önce şunu, sonra şunu yap" diyebilecek düzeyde konuya hâkim olmanız.

cPanel Node.js Yönetimi Perde Arkasında Nasıl Çalışır#

cPanel'in Node.js desteği kendi başına bir sihir değil; işi yapan bileşen Phusion Passenger. Passenger, Apache veya LiteSpeed web sunucusuyla entegre çalışan bir uygulama sunucusudur. Ziyaretçi alan adınıza istek attığında istek önce web sunucusuna düşer, web sunucusu bu isteği Passenger'a devreder, Passenger da sizin Node uygulamanızı arka planda ayağa kaldırıp isteği ona iletir. Yani klasik "terminalde node çalıştır, 3000 portunu dinle, nginx ile önüne proxy koy" zincirini Passenger sizin yerinize kurar.

Bu mimarinin en önemli sonucu şudur: uygulamanızın dinleyeceği portu siz belirlemezsiniz. Passenger uygulamayı başlatırken ona bir soket veya port atar ve bunu ortam değişkeni (process.env.PORT) üzerinden bildirir. Kodunuzda app.listen(3000) gibi sabit bir port yazarsanız uygulama paylaşımlı ortamda ya hiç açılmaz ya da beklenmedik biçimde davranır. Doğrusu her zaman app.listen(process.env.PORT) yazmaktır. cPanel/Passenger ortamında bu detay, yeni başlayanların en sık takıldığı noktadır ve ileride ayrı bir başlıkta ayrıntısıyla ele alacağım.

Passenger ayrıca uygulamanızın yaşam döngüsünü de yönetir. Uzun süre istek gelmezse süreci uyku moduna alabilir, ilk istekte tekrar uyandırır; kod değiştiğinde restart.txt adlı bir dosyaya bakarak yeniden başlatır; çökme durumunda tekrar ayağa kaldırmaya çalışır. Bu yönüyle Passenger, PM2 veya systemd'nin paylaşımlı hostingteki karşılığı gibi düşünülebilir. cPanel'in ne olduğu ve panelin genel mantığı konusunda temeliniz eksikse önce cPanel nedir yazısına göz atmanız, buradaki adımları daha rahat oturtmanıza yardımcı olur.

Ön Hazırlık ve Uygulama Kök Dizinini Planlamak#

İşe başlamadan önce iki şeyi netleştirin: uygulamanızın kodu nereye yüklenecek ve hangi alan adı ya da alt alan adı üzerinden yayınlanacak. cPanel'de Node uygulamaları genellikle ana web kök dizini olan public_html içine değil, onun dışında ayrı bir klasöre yerleştirilir. Bunun nedeni, Passenger'ın uygulama kökü ile web'e açık dizini ayrı tutmasıdır; node_modules, kaynak kodları ve .env benzeri hassas dosyaların doğrudan tarayıcıdan erişilebilir olmasını istemezsiniz.

Tipik bir yerleşim şöyledir. Ev dizininizde uygulamaya özel bir klasör açarsınız:

# SSH ile bağlandıysanız
mkdir -p ~/nodeapps/benim-api
cd ~/nodeapps/benim-api

Uygulama kök dizini ~/nodeapps/benim-api olacak; başlangıç dosyanız (örneğin app.js veya server.js) bu klasörün içinde yer alacak. Kodunuzu buraya iki yolla taşıyabilirsiniz: cPanel Dosya Yöneticisi üzerinden bir zip yükleyip açarak ya da SSH erişiminiz varsa doğrudan Git ile klonlayarak.

# Git ile çekmeyi tercih ederseniz
cd ~/nodeapps
git clone https://github.com/kullanici/benim-api.git benim-api

Uygulamanızı bir alt alan adında yayınlamak istiyorsanız (örneğin api.alanadiniz.com), önce cPanel'in "Subdomains" bölümünden bu alt alan adını oluşturmanız pratik olur. Kök alan adında yayınlayacaksanız buna gerek yok. Kök dizin ile web dizini arasındaki ayrımı şöyle özetleyebiliriz:

Bu dört kavramı baştan doğru planlarsanız kurulumun geri kalanı büyük ölçüde form doldurmaktan ibaret kalır. Hosting paketinizin Node.js sürümlerini ve SSH erişimini destekleyip desteklemediğinden emin değilseniz, web hosting paketleri sayfasındaki özellik listesini kontrol edebilir ya da bir sonraki adıma geçmeden destek ekibine sorabilirsiniz.

Setup Node.js App ile Uygulamayı Oluşturmak#

Hazırlık tamamsa asıl kuruluma geçelim. cPanel ana ekranında "Software" (Yazılım) grubu altında "Setup Node.js App" simgesini bulun ve tıklayın. Açılan ekranda mevcut Node uygulamalarınız listelenir; ilk kez kuruyorsanız liste boştur. Sağ üstteki "Create Application" (Uygulama Oluştur) düğmesiyle yeni bir uygulama tanımlarsınız.

Karşınıza çıkan formda doldurmanız gereken alanlar şunlardır. Node.js version kısmından uygulamanızın uyumlu olduğu sürümü seçin; kararlı LTS sürümleri (örneğin 18.x veya 20.x) çoğu proje için doğru tercihtir, en yeni sürümü seçmek her zaman iyi fikir değildir çünkü bazı paketler henüz uyumlu olmayabilir. Application mode genellikle "Production" bırakılır; geliştirme aşamasında ayrıntılı hata mesajları görmek isterseniz geçici olarak "Development" seçebilirsiniz. Application root alanına biraz önce oluşturduğunuz klasörün ev dizinine göre yolunu yazın (örneğin nodeapps/benim-api). Application URL alanında uygulamanın yayınlanacağı alan ya da alt alan adını seçin. Application startup file alanına başlangıç dosyanızın adını girin (örneğin app.js).

Startup file konusunda bir noktaya dikkat çekmek isterim: bu dosyanın export ettiği ya da listen çağırdığı şey Passenger'ın tutacağı uygulamadır. Basit bir Express örneği şöyle görünür ve port yönetimi açısından doğru yazılmıştır:

// app.js
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Merhaba, cPanel üzerinde Node.js çalışıyor!');
});

// Portu ASLA sabit yazmayın; Passenger PORT değişkenini verir
const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Uygulama ${port} portunda dinliyor`);
});

Formu doldurup "Create" dediğinizde cPanel arka planda birkaç iş yapar: seçtiğiniz Node sürümü için izole bir sanal ortam (virtual environment) oluşturur, uygulama URL'sine karşılık gelen Passenger yapılandırmasını yazar ve uygulama kök dizininde public gibi gerekli bağlantıları hazırlar. Bu noktada uygulamanız teknik olarak tanımlıdır ancak bağımlılıkları henüz kurulmadığı için büyük olasılıkla hata verecektir. Bir sonraki adımda bunu çözeceğiz. Bu konteyner benzeri izolasyon mantığını daha derinlemesine merak ediyorsanız, farklı bir soyutlama katmanı olan Docker'ı anlatan Docker nedir başlangıç yazısı iyi bir karşılaştırma sunar.

npm Bağımlılıklarını Kurmak#

Uygulama oluşturulduğunda cPanel size uygulamaya özel bir sanal ortam tanımlar ve bu ortamı aktive eden bir komut verir. Setup Node.js App ekranında uygulamanızı genişlettiğinizde, en üstte "Enter to the virtual environment" başlığı altında şuna benzer bir satır görürsünüz:

source /home/kullanici/nodevenv/nodeapps/benim-api/20/bin/activate && cd /home/kullanici/nodeapps/benim-api

Bu komutu SSH oturumunuzda çalıştırdığınızda, o kabuk artık uygulamanız için ayrılan Node ve npm sürümünü kullanır. Sistemin genel Node'unu değil, tam olarak uygulamanızın seçtiği sürümü kullanmanız önemlidir; aksi halde geliştirme ile üretim arasında sürüm farkından kaynaklı hatalar yaşarsınız. Ortamı aktive ettikten sonra bağımlılıkları kurmak standart bir komuttur:

# Sanal ortam aktifken
npm install

SSH erişiminiz yoksa endişelenmeyin. Setup Node.js App ekranında, uygulama detaylarının içinde "Run NPM Install" adında bir düğme bulunur. Uygulama kökünüzde geçerli bir package.json varsa bu düğmeye tıklamanız yeterlidir; cPanel bağımlılıkları arayüz üzerinden kurar. Aynı ekrandaki "Run JS script" alanından package.json içindeki script'leri (örneğin bir build adımı) de çalıştırabilirsiniz.

Bağımlılık kurulumunda karşılaşabileceğiniz birkaç tipik durum var. Bellek sınırına takılan büyük kurulumlar için package-lock.json dosyanızın kod ile birlikte yüklü olduğundan emin olun; bu, kurulumu hem hızlandırır hem tekrarlanabilir kılar. Yerel makinenizde derlenen node_modules klasörünü zip içine koyup sunucuya taşımak genelde iyi fikir değildir çünkü işletim sistemi ve mimari farkları yüzünden derlenmiş (native) modüller çalışmayabilir; bağımlılıkları her zaman sunucuda kurun. Kurulum bittikten sonra uygulama detay ekranındaki "Restart" düğmesiyle uygulamayı yeniden başlatmayı unutmayın, aksi halde yeni paketler yüklenmiş süreçte etkin olmaz.

Ortam Değişkenlerini Tanımlamak#

Gerçek uygulamalar veritabanı bağlantı bilgisi, API anahtarı, JWT gizli anahtarı gibi hassas değerlere ihtiyaç duyar. Bunları koda gömmek hem güvenlik açısından sakıncalı hem de bakım açısından zahmetlidir; doğrusu ortam değişkenleri (environment variables) kullanmaktır. cPanel'in Setup Node.js App ekranı bunun için özel bir bölüm sunar: uygulama detaylarını açtığınızda "Environment variables" alanında "Add Variable" düğmesiyle isim-değer çiftleri ekleyebilirsiniz.

Örneğin bir veritabanı bağlantısı ve uygulama ortamı için şu değişkenleri tanımlayabilirsiniz:

NODE_ENV=production
DB_HOST=localhost
DB_USER=kullanici_db
DB_PASS=guclu-bir-parola
DB_NAME=kullanici_app
JWT_SECRET=rastgele-uzun-bir-anahtar

Bu değişkenler uygulamanız çalışırken process.env üzerinden erişilebilir olur. Kodunuzda kullanımı gayet basittir:

const pool = mysql.createPool({
  host: process.env.DB_HOST,
  user: process.env.DB_USER,
  password: process.env.DB_PASS,
  database: process.env.DB_NAME,
});

Panel üzerinden eklenen değişkenlerin yanı sıra, geliştiriciler çoğu zaman uygulama kökünde bir .env dosyası tutmayı ve dotenv paketiyle okumayı tercih eder. İki yöntemi birlikte de kullanabilirsiniz, ancak .env dosyanızın web kökünde değil uygulama kökünde durduğundan ve dolayısıyla tarayıcıdan erişilemediğinden emin olun. Bir noktayı özellikle vurgulamak isterim: ortam değişkenlerini her ekleyip değiştirdiğinizde uygulamayı yeniden başlatmanız gerekir; Passenger değişiklikleri ancak süreç yeniden başladığında okur. Bir veritabanı oluşturmayı ve kullanıcı yetkilendirmesini henüz yapmadıysanız, cPanel'in "MySQL Databases" bölümünden veritabanınızı ve kullanıcınızı oluşturup yukarıdaki değişkenlere aynı bilgileri girmeniz gerekir.

Uygulamayı Başlatma, Yeniden Başlatma ve Durdurma#

Kurulum tamamlandığında uygulamanızı çalışır durumda tutmak ve gerektiğinde yeniden başlatmak günlük rutininizin parçası olur. cPanel'in Setup Node.js App ekranı bunun için birkaç düğme sunar. Uygulama detaylarını açtığınızda sağ üstte "Restart", "Stop" ve gerektiğinde "Start" düğmelerini görürsünüz. Kodda değişiklik yaptıysanız, yeni bir paket kurduysanız ya da ortam değişkeni değiştirdiyseniz "Restart" düğmesi ihtiyacınızı karşılar.

SSH ile çalışmayı sevenler için Passenger'ın kendi zarif yöntemi vardır: uygulama kökünde tmp/restart.txt adında bir dosyaya dokunmak. Passenger bu dosyanın değişiklik zamanını izler ve dosyaya her dokunulduğunda bir sonraki istekte uygulamayı yeniden başlatır. Bu, dağıtım (deploy) script'lerine koymak için ideal bir komuttur:

# Uygulama kökünde
mkdir -p tmp
touch tmp/restart.txt

Tipik bir güncelleme akışı şöyle işler ve bunu bir kabuk script'i haline getirebilirsiniz:

cd ~/nodeapps/benim-api
git pull origin main
source /home/kullanici/nodevenv/nodeapps/benim-api/20/bin/activate
npm install --production
touch tmp/restart.txt

Uygulamayı tamamen durdurmak istediğinizde panelden "Stop" düğmesini kullanmak en temiz yoldur; bu, Passenger'a uygulamayı ayağa kaldırmamasını söyler. Geçici bakım için ise uygulamayı durdurup web köküne basit bir bakım sayfası koymak makul bir yaklaşımdır. Şunu unutmayın: paylaşımlı hostingte uzun süre trafik almayan bir uygulama Passenger tarafından uyku moduna alınabilir; bu normaldir ve ilk istekte birkaç saniyelik bir "soğuk başlama" gecikmesi dışında bir soruna yol açmaz. Sürekli düşük gecikme gerektiren yoğun uygulamalar için paylaşımlı ortam yerine kaynakları size ayrılmış bir VDS sunucu ya da genel olarak sunucu çözümleri daha uygun olur.

Port Yönetimi ve Passenger Reverse Proxy Mantığı#

Node dünyasından gelenlerin cPanel ortamında en çok kafasını karıştıran konu port meselesidir. Kendi VPS'inizde uygulamanızı 3000 portunda çalıştırıp önüne bir nginx reverse proxy koymaya alışkınsınızdır. Referans olması açısından, kendi sunucunuzda böyle bir yapılandırma kabaca şuna benzer:

server {
    listen 80;
    server_name api.alanadiniz.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

cPanel/Passenger ortamında ise bu yapılandırmayı siz yazmazsınız; Passenger web sunucusuyla entegre olduğu için reverse proxy katmanını kendisi kurar. Uygulamanız için bir port açıp onu dışarıya proxylemek yerine, Passenger uygulamayı başlatırken ona dinlemesi gereken adresi PORT ortam değişkeni ile bildirir. Sizin tek sorumluluğunuz bu değişkeni okumaktır. İşte bu yüzden başlangıçta ısrarla app.listen(process.env.PORT) yazın dedim.

Yaygın bir hata, uygulamanın hem process.env.PORT hem de sabit bir port arasında karar vermeye çalışmasıdır. Aşağıdaki iki satırın farkı bu ortamda hayati önemdedir:

// YANLIŞ: paylaşımlı ortamda çalışmaz
app.listen(3000);

// DOĞRU: Passenger ne verirse onu dinler
app.listen(process.env.PORT || 3000);

İkinci satırdaki || 3000 yalnızca yerel geliştirme için bir yedek değerdir; sunucuda Passenger her zaman gerçek bir PORT sağladığı için 3000'e hiç düşülmez. Aynı mantık host adresi için de geçerlidir; genellikle adres belirtmeden yalnızca portu vermek yeterlidir, çünkü Passenger bağlantıyı kendi soketi üzerinden yönlendirir. Uygulamanızın HTTPS ile güvenli sunulması da yine sizin işiniz değildir; SSL sonlandırması web sunucusu katmanında yapılır. Alan adınızda ücretsiz ya da ticari bir sertifikayı devreye almak için cPanel'in SSL/TLS bölümünü ya da SSL sertifikası hizmetini kullanabilir, gelen trafiği ek olarak korumak isterseniz WAF ve DDoS koruma katmanlarını değerlendirebilirsiniz.

Log Takibi ve Sorun Giderme#

Er ya da geç uygulamanız beklediğiniz gibi çalışmaz; işte o an logları okumayı bilmek işinizi kurtarır. Passenger tabanlı bir uygulamada başvuracağınız birkaç ana log kaynağı vardır. İlki uygulamanızın kendi stderr çıktısıdır; kodunuzda console.error ile yazdığınız her şey buraya düşer. İkincisi web sunucusunun hata günlükleridir; genellikle ev dizininizde ~/logs altında ya da uygulama URL'sine özel bir dosyada bulunur.

En pratik yöntem, uygulama kökünde bir log dizini tutup canlı olarak izlemektir:

# Passenger ve uygulama loglarını canlı izleyin
tail -f ~/nodeapps/benim-api/stderr.log

# Web sunucusu hata loglarına da bakın
tail -f ~/logs/api.alanadiniz.com.error.log

Karşılaşacağınız hataların büyük kısmı birkaç tipik kategoriye girer. En sık görülen "503 Service Unavailable" ya da Passenger'ın "Error starting application" ekranıdır; bu genellikle uygulamanın hiç ayağa kalkamadığı anlamına gelir. Sık rastlanan nedenler ve çözümleri şöyle özetlenebilir:

Sorun giderirken izleyeceğim sıra hemen her zaman aynıdır. Önce başlangıç dosyasının adının ve uygulama kökünün panelde doğru yazıldığını kontrol ederim. Ardından sanal ortamı aktive edip uygulamayı elle node app.js ile çalıştırıp hatayı doğrudan görmeye çalışırım; bu, Passenger'ın soyutladığı hatayı çıplak biçimde ekrana getirdiği için en hızlı teşhis yöntemidir. Uygulama elle çalışıyor ama Passenger üzerinden çalışmıyorsa neredeyse her zaman port ya da ortam değişkeni sorunu vardır. Son olarak npm installı temiz bir node_modules ile tekrarlar ve tmp/restart.txt ile yeniden başlatırım. Bu disiplinli sıra, çoğu problemi birkaç dakikada çözer. Sorunu bir türlü izole edemediğiniz durumlarda ise sunucu yönetimi hizmetiyle uzman desteği almak, saatlerce log kurcalamaktan daha verimlidir.

Sıkça Sorulan Sorular#

cPanel'de her Node.js uygulaması çalışır mı?#

Genel olarak evet, ancak birkaç kısıt vardır. Passenger; Express, Koa, Fastify gibi standart Node HTTP sunucularını ve SSR yapan çatıları sorunsuz çalıştırır. Sürekli açık kalması gereken WebSocket yoğun uygulamalar, arka planda ağır ve kesintisiz işlem yapan servisler ya da özel sistem kütüphaneleri gerektiren projeler paylaşımlı ortamın kaynak ve süreç sınırlarına takılabilir. Böyle durumlarda uygulamanızı sanal ya da fiziksel bir sunucuya taşımak daha doğru olur.

Kodumu güncellediğimde uygulama otomatik yenileniyor mu?#

Hayır, otomatik değil. Passenger yalnızca tmp/restart.txt dosyasının değişiklik zamanını ya da paneldeki "Restart" düğmesini takip eder. Yeni kodu sunucuya yükledikten sonra ya bu dosyaya dokunmanız ya da panelden yeniden başlatmanız gerekir; aksi halde Passenger halen bellekteki eski süreci kullanmaya devam eder. Bu adımı dağıtım script'inize eklemek en pratik çözümdür.

Uygulamam neden 3000 portunda açılmıyor?#

Çünkü paylaşımlı hostingte dinleyeceğiniz portu siz değil Passenger belirler. Kodunuzda sabit bir port yazdıysanız uygulama Passenger'ın atadığı adreste dinlemediği için isteklere yanıt veremez. Çözüm, app.listen(process.env.PORT) yazarak Passenger'ın verdiği portu okumaktır. Yerel geliştirme için process.env.PORT || 3000 biçiminde bir yedek değer eklemek zararsızdır ve sunucuda hiç devreye girmez.

npm install düğmesi çalışmıyorsa ne yapmalıyım?#

Önce uygulama kökünüzde geçerli bir package.json dosyasının bulunduğundan emin olun; düğme bu dosya olmadan iş yapmaz. Sorun sürerse SSH erişiminiz varsa sanal ortamı aktive edip npm install komutunu elle çalıştırarak gerçek hata mesajını görebilirsiniz. Bellek ya da zaman aşımı hataları alıyorsanız package-lock.json dosyanızı yükleyip kurulumu yalnızca üretim bağımlılıklarıyla (npm install --production) denemek çoğu zaman sorunu çözer.

Node.js sürümünü sonradan değiştirebilir miyim?#

Evet. Setup Node.js App ekranında uygulamanızın detaylarını açıp Node.js version alanından farklı bir sürüm seçebilir ve kaydedebilirsiniz. Sürüm değiştikten sonra bağımlılıkları yeniden kurmanız (npm install) ve uygulamayı yeniden başlatmanız gerekir, çünkü derlenmiş bazı paketler önceki sürüme göre kurulmuş olabilir. Üretimdeki bir uygulamada sürüm yükseltmesini önce mümkünse bir alt alan adında deneyerek yapmanızı öneririm.

Uygulamamı alan adının kök dizininde mi yayınlamalıyım?#

Tercihe bağlıdır. API veya arka uç servisi genellikle api.alanadiniz.com gibi bir alt alan adında yayınlanır; böylece kök alan adı statik site ya da WordPress için serbest kalır. Tek bir Node uygulaması tüm siteyi karşılayacaksa kök alan adında yayınlamak da uygundur. Her iki durumda da uygulama kodunuzu public_html dışında, ayrı bir uygulama kökünde tutmanız güvenlik açısından önemlidir.

Kapanış#

cPanel'in Setup Node.js App aracı, Passenger'ın gücünü panel arkasına gizleyerek Node uygulaması yayınlamayı sürpriz derecede basit hale getiriyor. Doğru uygulama kökünü ve başlangıç dosyasını seçmek, uygun Node sürümünü belirlemek, npm install ile bağımlılıkları kurmak, ortam değişkenlerini tanımlamak ve her değişiklikte uygulamayı yeniden başlatmak; işte günlük iş akışınızın tamamı bundan ibaret. Bir tek altın kuralı aklınızda tutun: portu asla sabit yazmayın, her zaman process.env.PORT değerini dinleyin. Bu tek satır, paylaşımlı hostingte yaşanan sorunların büyük çoğunluğunu baştan önler.

Node uygulamanız büyüdükçe kaynak ihtiyacınız da artar; paylaşımlı bir pakette başlayıp ihtiyaç duyduğunuzda daha güçlü bir yapıya geçmek en sağlıklı yoldur. Node.js destekli, SSD tabanlı ve hızlı web hosting paketlerimize göz atabilir, projeniz kaynak açısından büyüdüğünde kontrolün tamamen sizde olduğu VDS ve sunucu çözümlerimizi inceleyebilirsiniz. Alan adınızı, SSL'inizi ve uygulamanızı tek bir çatı altında toplamak için alan adı tarafına da bakmanızı, kurulumda takıldığınız her noktada Clou.TR ekibinden destek istemenizi öneririz.