Deploy seçenekleri

Dört Yol

Next.js dört şekilde yayınlanabilir:¹

Next.js dokümanı minimum gereksinimi tek cümleyle söyler: Next.js'i çalıştırmak için platformun bir Node.js sunucusu sağlaması yeterlidir. Tek bir next start süreci Server Components, Server Actions, Cache Components, proxy ve after() dahil her özelliği doğru çalıştırır.²

Adaptörler ve Platformlar

Platformlar Next.js'i kendi altyapısına Deployment Adapter API ile uyarlar. Açık kaynak olan ve Next.js uyumluluk test paketini çalıştıran adaptörlere doğrulanmış (verified) adaptör denir. Bu rehber yazılırken doğrulanmış adaptörler Vercel ve Bun'dır; Cloudflare ve Netlify kendi adaptörleri üzerinde çalışıyor.¹²

Doküman iki kavramı ayırır:²

• İşlevsel doğruluk: Her özellik doğru çalışır mı? Test paketi bunun ölçüsüdür; geçer ya da geçmez.

• Performans doğruluğu: Özellikler en iyi performansla mı çalışır? Örneğin statik kabuğun CDN'den sunulması. Bu bir yelpazedir ve platformlar burada ayrışır.

Vercel'de deploy etmek için depoyu bağlamak yeterlidir; her pull request bir önizleme adresi, main canlı ortam olur. Kendi sunucunuzda ise bu işleri sizin kurmanız gerekir. Bu dersin geri kalanı o işleri anlatır.

Node.js Sunucusu

En sade yol, package.json'daki iki betiktir:¹

$ pnpm build
npm run start

next build uygulamayı derler, next start production sunucusunu başlatır. Sunucuda kaynak kodun ve tüm node_modules'ın bulunması gerekir.

Standalone Çıktı

output: "standalone" build sırasında yalnızca çalışmak için gereken dosyaları .next/standalone klasörüne toplar. Kullanılan paketlerin yalnızca gereken dosyaları kopyalanır; klasör node_modules kurulmadan tek başına deploy edilebilir:³

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "standalone",
};

export default nextConfig;

Klasörde next start yerine kullanılan küçük bir server.js vardır. İki şeye dikkat:³

1. public ve .next/static klasörleri kopyalanmaz; doküman bunların ideal olarak bir CDN'den sunulmasını bekler. Sunucunun kendisi sunacaksa elle kopyalayın:

   pnpmyarnnpmbun

   $ cp -r public .next/standalone/ && cp -r .next/static .next/standalone/.next/

2. Port ve adres PORT ve HOSTNAME ortam değişkenleriyle verilir:

   pnpmyarnnpmbun

   $ PORT=8080 HOSTNAME=0.0.0.0 node .next/standalone/server.js

Docker İmajı

Docker dokümanı çok aşamalı (multi-stage) build önerir: her FROM yeni bir aşama başlatır ve son imaja yalnızca çalışmak için gereken dosyalar kopyalanır. İmaj küçülür; derleme araçları ve kaynak kod son imajda kalmaz.⁴⁵ Next.js'in resmi Docker örneği bu yapıyı standalone çıktıyla kullanır:⁶

# syntax=docker/dockerfile:1
ARG NODE_VERSION=24-slim

# 1. aşama: bağımlılıklar. Yalnızca paket dosyaları değişince yeniden çalışır.
FROM node:${NODE_VERSION} AS dependencies
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci --no-audit --no-fund

# 2. aşama: build.
FROM node:${NODE_VERSION} AS builder
WORKDIR /app
COPY --from=dependencies /app/node_modules ./node_modules
COPY . .
ENV NODE_ENV=production
RUN npm run build

# 3. aşama: çalışma imajı.
FROM node:${NODE_VERSION} AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=3000
ENV HOSTNAME=0.0.0.0

COPY --from=builder --chown=node:node /app/.next/standalone ./
COPY --from=builder --chown=node:node /app/.next/static ./.next/static

USER node
EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
  CMD ["node", "-e", "fetch('http://127.0.0.1:3000/api/health').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]

CMD ["node", "server.js"]

Satır satır gerekçeler:

• Paket dosyalarını önce kopyalamak: Docker her adımı önbelleğe alır. Kaynak kod değişip package-lock.json değişmediyse npm ci yeniden çalışmaz.⁵

• node:24-slim: Etiketi sabitleyin; node:latest bir gün sessizce yeni bir sürüme geçer. OWASP'ın Node.js Docker rehberi de açık ve sabit imaj etiketleri önerir.⁷

• USER node: Node.js imajları root olmayan node kullanıcısıyla gelir. Konteyneri root olarak çalıştırmamak, bir açık bulunduğunda saldırganın elindeki yetkiyi sınırlar.⁷

• CMD ["node", "server.js"]: Exec biçimi süreci bir kabuk (shell) olmadan başlatır ve sinyaller doğrudan sürece ulaşır. npm start ise SIGTERM gibi sinyalleri Node.js sürecine iletmez.⁷

• HEALTHCHECK: Docker uygulamanın gerçekten yanıt verip vermediğini düzenli kontrol eder. Slim imajda curl yoktur; Node.js'in kendi fetch'i yeterlidir.

.dockerignore build bağlamına gereksiz dosyaların girmesini önler.⁵ Yerel node_modules, .next, testler ve özellikle .env* dosyaları imaja girmemelidir:

# .dockerignore
node_modules
.next
.git
.env*
!.env.example
tests
playwright-report

$ docker build -t order-panel .
docker run --rm -p 3000:3000 -e APP_ENV=preview -e APP_VERSION=1.0.0 order-panel

Ortam değişkenleri docker run -e ile çalışma anında verilir. Aynı imaj önizlemede ve canlıda farklı değerlerle çalışır (bkz. Ortam değişkenleri).

Sağlık Kontrolü

Bir konteyner platformu, yük dengeleyici ya da Docker'ın HEALTHCHECK'i uygulamanın ayakta olup olmadığını bir HTTP uç noktasıyla sorar:

// app/api/health/route.ts
import { connection } from "next/server";
import { getEnv } from "@/lib/env";

export async function GET() {
  await connection();
  const { APP_ENV, APP_VERSION } = getEnv();

  return Response.json(
    { status: "ok", env: APP_ENV, version: APP_VERSION },
    { headers: { "Cache-Control": "no-store" } },
  );
}

• connection() yanıtın build sırasında üretilip saklanmasını önler. Sağlık kontrolü her seferinde gerçekten çalışmalıdır.

• version alanı canlıda hangi sürümün çalıştığını tek komutla gösterir. Bir deploy'un yayına çıkıp çıkmadığını anlamanın en kısa yoludur.

• Uç noktayı hafif tutun. Her kontrol bir veritabanı sorgusu yaparsa sağlık kontrolü yük oluşturur.

Kendi Sunucunuzda Dikkat Edilecekler

Next.js'in kendi sunucunuzda barındırma rehberi şunları ister:⁹

Bu rehberin projesindeki imajda docker stop bir saniyeden kısa sürede temiz kapanır: Next.js sunucusu SIGTERM'i kendisi dinler ve süreç doğrudan node ile başlatıldığı için sinyal ona ulaşır.

Hangisini Seçmeli?

Kendin Dene

• Projenize output: "standalone" ekleyin, build alın ve .next/standalone klasörünün boyutunu node_modules ile karşılaştırın.

• Dockerfile'ı yazın ve imajı oluşturun. docker image ls ile boyutuna bakın; çok aşamalı yapıyı tek aşamaya indirip farkı görün.

• Konteyneri başlatıp docker inspect -f '{{.State.Health.Status}}' ile sağlık durumunu izleyin.

• CMD'yi npm start yapıp docker stop'un ne kadar sürdüğünü ölçün; sonra geri alın.

Detaylı Öğrenmek İçin

• Resmi doküman: Next.js, "Deploying" ve "Deploying to Platforms"; seçenekler, adaptörler ve özellik gereksinimleri.¹²

• Resmi doküman: Next.js, "Self-Hosting"; ters vekil, önbellek, sürüm farkı ve kapanış.⁹

• Resmi doküman: Docker, "Building best practices"; çok aşamalı build, önbellek ve .dockerignore.⁵

• Rehber: OWASP, "Node.js Docker Cheat Sheet"; root olmayan kullanıcı, sinyaller ve secret'lar.⁷