Adım Adım Node.js Projesi Sunucuya Yüklemek

Node.js Hosting paketlerimizde bir Express, Fastify veya NestJS uygulamasını yayına almak için sunucuya SSH ile bağlanmanız şart değil. İşlemlerin tamamı Plesk panelindeki Node.js Toolkit üzerinden yapılabiliyor. Bu yazımızda sıfırdan bir Node.js projesini adım adım yayına alıyor, veritabanı bağlantısını kuruyor ve en sık karşılaşılan hataların önüne nasıl geçeceğimizi anlatıyoruz.

Node.js Hosting paketlerinde neler hazır geliyor?

Paketleri teslim ettiğimizde sunucu tarafında şunlar kurulu ve kullanıma hazır olarak gelir:

• Node.js sürümleri: Yeni projeler için Node.js 24 LTS, mevcut projeler için 22 LTS önerilir. 20 sürümü de kullanılabilir durumdadır. Farklı bir sürüme ihtiyacınız varsa destek ekibimizle iletişime geçebilirsiniz.

• Paket yöneticileri: npm ve Yarn kuruludur; Corepack ile pnpm de etkinleştirilebilir.

• Uygulama sunucusu: Uygulamanız Phusion Passenger tarafından çalıştırılır ve arka planda ayakta tutulur. Ayrıca bir süreç yöneticisi kurmanıza gerek yoktur.

• Veritabanı: MariaDB 10.11 ve PostgreSQL desteklenir.

• Geliştirici araçları: Git, panel içinden SSH terminali, zamanlanmış görevler (cron), günlük (log) görüntüleyici ve ücretsiz Let's Encrypt SSL sertifikası.

• Kaynak yönetimi: CloudLinux ile her hesap kendi kaynak sınırları içinde izole çalışır; bir sitenin yükü diğerlerini etkilemez.

Paketlerin kaynak sınırları ise şöyledir:

Başlamadan önce projenizde olması gerekenler

Kuruluma geçmeden önce projenizin şu üç şartı sağladığından emin olalım. Bu üç madde, destek taleplerinin büyük bölümünün kaynağıdır.

1. Geçerli bir package.json dosyası. Bağımlılıklarınız burada tanımlı olmalı:

{
  "name": "ornek-uygulama",
  "version": "1.0.0",
  "main": "app.js",
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "express": "^4.19.2"
  }
}

2. Tek bir başlangıç dosyası. Uygulamanız tek bir dosyadan ayağa kalkmalıdır. Yaygın adlandırma app.js veya server.js şeklindedir.

3. Portu kodun içine sabitlemeyin. Uygulamanız Passenger tarafından çalıştırılır ve gelen istekler ona yönlendirilir; app.listen() çağrısına verdiğiniz port değeri kullanılmaz. Projenizin başka ortamlarda da çalışabilmesi için yaygın kalıbı kullanmanızı öneririz:

const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Uygulama çalışıyor.');
});

app.listen(process.env.PORT || 3000);

NOT: Sunucumuzda PORT ortam değişkeni tanımlı değildir; process.env.PORT değerini ekrana yazdırırsanız undefined görürsünüz. Bu normaldir ve uygulamanızın çalışmasına engel değildir.

NOT: node_modules klasörünü ve .env dosyanızı Git deponuza göndermeyin. Bağımlılıkları sunucuda kuracağız, ortam değişkenlerini de panel üzerinden tanımlayacağız.

1. Adım: Alan adı için Node.js desteğini açmak

Plesk paneline giriş yaptıktan sonra Web Siteleri ve Alan Adları bölümünden ilgili alan adını seçiyor, Geliştirici Araçları altındaki Node.js simgesine tıklıyoruz.

Açılan ekranda Node.js Sürümü satırındaki sürüme tıklayarak projenizin çalışacağı sürümü seçiyoruz. Yeni bir proje kuruyorsanız 24 LTS'i, elinizde eski bir proje varsa 22 LTS'i seçmenizi öneririz. Sürümü sonradan bu ekrandan değiştirebilirsiniz.

Yeni oluşturulan paketlerde varsayılan sürüm 24 LTS'tir. Yine de bu alanı kontrol edip projenizin ihtiyaç duyduğu sürümü seçmenizi öneririz.

Aynı ekranda Uygulama Modu alanının production olduğunu doğrulayın. Geliştirme modunda çalıştırmak hem yavaştır hem de hata detaylarını ziyaretçilere gösterir.

2. Adım: Proje dosyalarını sunucuya yüklemek

Dosya Yöneticisi ile

Küçük projeler için en pratik yol panelin Dosya Yöneticisi'dir. Alan adınızın kök dizinine girip proje dosyalarınızı yükleyin veya bir zip arşivini yükleyip panel üzerinden çıkartın.

Git ile

Sürekli geliştirdiğiniz bir proje varsa Git kullanmanızı öneririz. Panelde Geliştirici Araçları altındaki Git bölümünden deponuzu bağlayabilir, her güncellemede tek tıkla dosyaları çekebilirsiniz. Kurulum adımları için Github üzerinden güncelleme işlemi yazımızdaki yöntem birebir geçerlidir.

3. Adım: Bağımlılıkları kurmak

Dosyalar yerine geldikten sonra Node.js ekranındaki NPM kurulumu düğmesine basmanız yeterlidir. Panel, package.json dosyanızı okuyup bağımlılıkları kurar.

Derleme adımı gerektiren projelerde (örneğin bir build komutu çalıştırmanız gerekiyorsa) aynı sayfadaki Node.js komutlarını çalıştır sekmesini kullanabilirsiniz. Bu sekmede sürümü ve paket yöneticisini seçip komutunuzu yazmanız yeterli; SSH bağlantısı kurmanıza gerek kalmaz.

Yarn kullanan bir projeniz varsa Paket Yöneticisi satırından bunu değiştirebilirsiniz. Panel, projenizdeki kilit dosyasına bakarak paket yöneticisini otomatik tespit eder, ancak tespit yanlışsa elle düzeltebilirsiniz.

NOT: Kilit dosyanızı (package-lock.json veya yarn.lock) da sunucuya yükleyin. Böylece sunucuda kurulan sürümler, yerelde geliştirdiğiniz sürümlerle birebir aynı olur.

4. Adım: Uygulama kökü ve başlatma dosyası

Node.js ekranındaki iki alan uygulamanızın çalışıp çalışmayacağını doğrudan belirler:

• Uygulama Kökü: package.json dosyanızın bulunduğu dizin.

• Uygulamayı Başlatma Dosyası: Uygulamayı ayağa kaldıran dosyanın adı.

Başlatma dosyası alanındaki değer, sunucudaki dosyanın adıyla birebir aynı olmalıdır. Varsayılan değer app.js'tir; projenizde dosyanın adı server.js veya index.js ise bu alanı da güncellemeniz gerekir. Aksi hâlde uygulamanız açılmaz.

Başlatma dosyası kök dizinde olmak zorunda değildir. Derleme üreten projelerde dist/server/entry.mjs gibi bir alt dizin yolu da yazabilirsiniz.

5. Adım: Belge kökünü güvenli hâle getirmek

Bu adım çoğu zaman atlanıyor, oysa güvenlik açısından en kritik olanı. Belge kökü, web sunucusunun ziyaretçilere doğrudan sunduğu dizindir. Belge kökü ile uygulama kökü aynı dizine ayarlanmışsa; .env dosyanız, package.json'ınız ve node_modules klasörünüz dışarıdan erişilebilir hâle gelir.

Bunu önlemek için statik dosyalarınızı uygulama kökünün altında ayrı bir dizinde (örneğin public/) toplayın ve Belge kökü alanını bu alt dizine ayarlayın. Plesk de bu ekranda aynı uyarıyı yapar.

ÖNEMLİ NOT: Uygulamanız yayına çıkmadan önce tarayıcınızdan alanadiniz.com/.env adresini deneyin. Dosyanın içeriği görünüyorsa veritabanı şifreniz ve API anahtarlarınız dışarıya açık demektir; belge kökünü hemen düzeltin.

6. Adım: Ortam değişkenlerini tanımlamak

Veritabanı şifresi, API anahtarı gibi bilgileri kodun içine yazmak yerine ortam değişkeni olarak tanımlamak gerekir. Node.js ekranındaki Özel ortam değişkenleri satırından belirt bağlantısına tıklayarak anahtar–değer çiftlerinizi ekleyebilirsiniz. Buraya girdiğiniz değerler uygulamanıza process.env üzerinden ulaşır.

Alternatif olarak proje kökünde bir .env dosyası tutup dotenv paketiyle okuyabilirsiniz. Bu yöntemi seçerseniz 5. adımdaki belge kökü uyarısını mutlaka uygulayın.

7. Adım: Veritabanı bağlantısı

Panelde Veritabanları bölümünden yeni bir veritabanı ve kullanıcı oluşturun. Uygulamanız veritabanıyla aynı sunucuda çalıştığı için bağlantı adresi localhost, port ise 3306 olacaktır.

Bağlantı bilgilerini 6. adımda anlattığımız şekilde ortam değişkeni olarak tanımladıktan sonra mysql2 paketiyle şu şekilde bağlanabilirsiniz:

const mysql = require('mysql2/promise');

const db = await mysql.createPool({
  host: process.env.DB_HOST,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  waitForConnections: true,
  connectionLimit: 10
});

Prisma, Sequelize, TypeORM, Knex ve Drizzle gibi kütüphanelerin tamamı MariaDB ile çalışır.

Karakter seti ve JSON alanlarına dikkat

MariaDB kullanırken iki noktaya dikkat etmenizi öneririz:

• Karakter seti: Bazı araçlar MySQL 8 varsayarak utf8mb4_0900_ai_ci karşılaştırma kuralını üretir; bu kural MariaDB'de bulunmaz. Türkçe karakterler için utf8mb4_general_ci veya utf8mb4_unicode_ci kullanın.

• JSON alanları: MariaDB'de JSON tipi, LONGTEXT üzerine tanımlı bir takma addır. JSON alanları üzerinde indeksleme ve sorgulama davranışı MySQL ile birebir aynı değildir; şemanızı buna göre tasarlayın.

PostgreSQL kullanmak isterseniz

Paketlerimizde PostgreSQL de sunulmaktadır. Projeniz PostgreSQL ile çalışıyorsa kurulumu birlikte yapmak üzere destek ekibimizle iletişime geçmenizi rica ederiz.

8. Adım: SSL sertifikası ve alan adı yönlendirmesi

Uygulamanız açıldıktan sonra son adım güvenli bağlantıdır. Panelden ücretsiz Let's Encrypt sertifikası kurabilir, ardından tüm trafiği HTTPS'e yönlendirebilirsiniz. Adımların tamamı SSL sertifikası ekleme ve yönlendirme yazımızda anlatılıyor.

Alan adınızın DNS kayıtlarını henüz yönlendirmediyseniz temel DNS işlemleri yazımızdan yararlanabilirsiniz.

Uygulamayı yeniden başlatma ve güncelleme

Node.js uygulamaları, PHP'den farklı olarak sürekli çalışan süreçlerdir. Bu nedenle dosyalarda yaptığınız değişiklikler kendiliğinden yansımaz. Şu üç durumda Uygulamayı yeniden başlat düğmesine basmanız gerekir:

• Kod dosyalarında değişiklik yaptıktan sonra,

• Yeni bağımlılık kurduktan sonra,

• Ortam değişkenlerini değiştirdikten sonra.

Yayındaki bir projeyi güncellerken izlenecek sıra şudur: önce dosyaları güncelleyin (Git ile çekin veya yükleyin), sonra NPM kurulumu'nu çalıştırın, en son Uygulamayı yeniden başlat deyin.

Kaynak limitleri: uygulamanız neden aniden duruyor?

Node.js uygulamaları uzun süre ayakta kaldığı için bellek kullanımları zamanla artabilir. Paketinizin bellek sınırına ulaşıldığında uygulama süreci sonlandırılır ve site hata vermeye başlar. Bu durumla karşılaşıyorsanız:

• Panelin Resource Usage ekranından hangi kaynağın sınıra dayandığını kontrol edin,

• Uygulamanızda bellek sızıntısı olup olmadığını inceleyin (kapatılmayan bağlantılar, sürekli büyüyen diziler ve önbellekler),

• Veritabanı bağlantı havuzunuzu makul bir sayıda tutun,

• İhtiyacınız gerçekten büyümüşse paketinizi daha yüksek bellekli bir pakete yükseltin.

Paketinizin uygulamanıza yetip yetmediğinden emin değilseniz, mevcut kaynak kullanımınızı birlikte inceleyip sizi yönlendirmemiz için destek ekibimize talep açabilirsiniz.

Uygulamanız açılmıyorsa hatayı nasıl görürsünüz?

Node.js uygulaması başlatılamadığında ziyaretçiye "We're sorry, but something went wrong" başlıklı genel bir hata sayfası gösterilir. Bu sayfa güvenlik gereği hatanın sebebini yazmaz, yalnızca bir Error ID verir.

Sebebi görmek için:

1. Node.js ekranında Uygulama Modu alanını geçici olarak development yapın.

2. Uygulamayı yeniden başlat deyin.

3. Sayfayı yenileyin. Bu kez ayrıntılı tanı sayfası açılır ve hatanın tam metnini gösterir; örneğin başlatma dosyası bulunamıyorsa Cannot find module '.../httpdocs/app.js' satırını görürsünüz.

   

4. Sorunu giderin ve Uygulama Modu'nu mutlaka production'a geri alın.

ÖNEMLİ NOT: development modu sunucudaki dosya yollarını ve hata yığınını sitenizi açan herkese gösterir. Yalnızca teşhis süresince açık kalmalı, sorun çözülür çözülmez production'a dönülmelidir.

Panelinizdeki Günlükler ekranında bu durumda yalnızca 500 yanıt kodları görünür; Node.js'in ürettiği hata metni orada yer almaz. Hata sayfasındaki Error ID'yi destek talebinize eklerseniz, sunucu tarafındaki kaydı bulup size dönebiliriz.

Sık karşılaşılan sorunlar

• Site açılmıyor, "something went wrong" sayfası geliyor. Uygulama başlatılamıyor demektir. Sebebini görmek için bir üstteki bölümdeki development adımını uygulayın. En sık nedenler: başlatma dosyasının adı paneldeki değerle aynı değil, bağımlılıklar kurulmamış, ya da koddaki bir hata uygulama açılırken patlıyor.

• Yaptığım değişiklik görünmüyor. Node.js uygulamaları bellekte çalışmaya devam eder. Dosyayı değiştirmeniz, hatta silmeniz bile çalışan süreci etkilemez; Uygulamayı yeniden başlat demeden hiçbir değişiklik yansımaz.

• Ortam değişkenleri okunmuyor. Değişkenleri ekledikten sonra uygulamanın yeniden başlatılması gerekir. .env dosyası kullanıyorsanız dosyanın uygulama kökünde olduğundan emin olun.

• Uygulama bir süre sonra duruyor. Büyük ihtimalle paketinizin bellek sınırına takılıyorsunuz; "Kaynak limitleri" bölümüne bakın.

Sıkça sorulan sorular

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

Yeni başlayan projeler için 24 LTS'i öneriyoruz. Elinizdeki proje daha eski bir sürümde geliştirildiyse 22 LTS güvenli bir tercihtir. Güncel olmayan sürümlerde çalışmak zorundaysanız destek ekibimizle iletişime geçin.

Node.js uygulaması yayına almak için SSH şart mı?

Hayır. Dosya yükleme, bağımlılık kurma, komut çalıştırma ve yeniden başlatma işlemlerinin tamamı panel üzerinden yapılabilir. Yine de isterseniz paketinizde SSH erişimi mevcuttur.

Aynı pakette birden fazla Node.js uygulaması çalıştırabilir miyim?

Evet. Paketinizin site sınırı kadar alan adı veya alt alan adı tanımlayıp her biri için ayrı bir Node.js uygulaması çalıştırabilirsiniz. Uygulamaların tamamı paketinizin ortak kaynak sınırlarını paylaşır.

Yarn veya pnpm kullanabilir miyim?

Yarn kuruludur ve panelden seçilebilir. pnpm için Corepack üzerinden etkinleştirme yapılması gerekir.

PM2 gibi bir süreç yöneticisi kurmam gerekir mi?

Hayır. Uygulamanız Passenger tarafından çalıştırılır ve ayakta tutulur; ayrıca bir süreç yöneticisine ihtiyaç duymazsınız.

Sonuç

Node.js projenizi yayına almak, doğru sürümü seçmek, bağımlılıkları kurmak ve başlatma dosyasını doğru tanımlamaktan ibaret. Kurulumda takılırsanız ya da projenizi bizim taşımamızı isterseniz 7/24 Türkçe destek ekibimize talep açmanız yeterli.

Henüz bir paketiniz yoksa Node.js Hosting paketlerimizi inceleyebilirsiniz.