Next.js 15 Standalone modu Docker ile nasıl kullanılır ve ne kazandırır?

next.config.js dosyasında output: "standalone" tanımlandığında Next.js derleyicisi, projenin çalışması için gereken tüm node_modules paketlerini ve sayfaları .next/standalone dizinine otomatik olarak paketler. Bu işlem imaj boyutunu ortalama 1 GB seviyesinden 80-120 MB aralığına indirir ve gereksiz devDependencies paketlerini üretim ortamından arındırır.

Neden tek aşamalı imaj yerine multi-stage (çok aşamalı) Dockerfile kullanılmalıdır?

Multi-stage derleme, uygulamanın derlenmesi için zorunlu olan ağır derleyicileri (TypeScript compiler, Cargo, Go SDK, C++ derleme araçları) son imajdan izole eder. Yalnızca üretilen saf binary veya standalone dosya final imajına kopyalanır. Böylece hem imaj indirme süreleri (pull) saniyelere iner hem de güvenlik açıklarının (CVE) sayısı radikal şekilde düşer.

Non-root kullanıcı (root yetkisiz çalıştırma) neden zorunlu bir DevSecOps kuralıdır?

Konteynerlerin varsayılan olarak root yetkisiyle çalıştırılması, uygulamada bir uzaktan kod yürütme (RCE) açığı bulunması durumunda saldırganın doğrudan host sunucu çekirdeğine (kernel) ve diğer konteynerlere sıçrama riskini (container breakout) doğurur. Non-root kullanıcı (örn: nextjs, appuser / UID 1001) tanımlamak en temel güvenlik zırhıdır.

Docker Compose v2 ortamında condition: service_healthy neden kullanılır?

Klasik depends_on komutu yalnızca bağlı konteynerin (örn: PostgreSQL) başlatılmasını bekler; ancak veritabanı portu henüz bağlantıları kabul etmeye hazır değildir ve ana uygulamanız çöker. HEALTHCHECK ile tanımlanan service_healthy koşulu, veritabanının gerçek anlamda hazır olduğunu onaylayana kadar ana uygulamanın başlamasını bekletir.

Python projelerinde Astral 'uv' kullanımı Docker build sürelerini nasıl etkiler?

Astral uv, Rust ile yazılmış son nesil bir Python paket yöneticisidir. Standart pip paket yöneticisine kıyasla paket çözümleme ve teker teker kurma işlemlerini 10 ila 100 kat daha hızlı gerçekleştirir. Dockerfile katman önbelleklemesiyle (layer caching) birleştiğinde CI/CD ve geliştirme derlemelerini devasa ölçüde hızlandırır.

DevSecOps & Container Architecture✓ Multi-Stage🛡️ Non-Root Ready⚡ Docker Compose v2

Dockerfile & Docker Compose Builder

Next.js 15+ (Standalone), Node.js, Python FastAPI (uv/pip), Go, Bun, Rust ve .NET 9 için üretime hazır, multi-stage hafif imajlar; PostgreSQL, Redis, MongoDB, RabbitMQ, MinIO servisleri ve tek tıkla .env.example konfigürasyonu üretin.

⚡ Multi-Stage Katmanlama

Derleyici araçlarını son imajdan atarak dosya boyutunu %90 küçültür (örn: 1 GB → 85 MB).

🛡️ Rootless DevSecOps

Root kullanıcısı yerine izole appuser tanımlayarak container breakout açıklarını önler.

💚 Akıllı Healthcheck

Veritabanı bağlantı kabul etmeden uygulamanın açılmasını engelleyerek çökme döngülerini bitirir.

Proje & Konteyner Ayarları

v2 Engine

Uygulama Mimarisi / Framework7 Çatı Destekli

Paket Yöneticisi & Lockfile

Uygulama Portu (EXPOSE)

Docker Compose ServisleriOtomatik Healthcheck

PostgreSQL 16

Veritabanı · 5432

Redis 7 Alpine

Cache & Kuyruk · 6379

MongoDB 7

NoSQL Belge · 27017

MySQL 8.4 LTS

İlişkisel Veritabanı · 3306

RabbitMQ 3

Mesaj Kuyruğu · 5672/15672

MinIO S3

Yerel Obje Depolama · 9000

Nginx Reverse Proxy

SSL & Yük Dengeleyici · 80/443

DevSecOps & Güvenlik Sertleştirmesi

Non-Root Kullanıcı (UID 1001)

Konteyneri root yerine kısıtlı kullanıcıyla çalıştırarak host sistemine sızma (container escape) riskini sıfırlar.

HEALTHCHECK Direktifi

Docker ve Kubernetes'in servis canlılığını periyodik denetlemesini ve çökme anında otomatik yeniden başlatmasını sağlar.

İmaj Boyutu~85 - 110 MB (Standalone)

Güvenlik🛡️ Non-Root

Canlılık💚 Healthcheck

Dockerfile

Multi-Stage Ready

# syntax=docker.io/docker/dockerfile:1
# Multi-Stage Production Dockerfile for Next.js 15+ App Router
# Output Mode: Standalone (Minimal Image Footprint ~90MB)

FROM node:20-alpine AS base

# 1. Dependencies stage: Cache packages before building
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

COPY package.json pnpm-lock.yaml* ./
RUN corepack enable pnpm && pnpm i --frozen-lockfile

# 2. Builder stage: Compile TypeScript & generate standalone output
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

ENV NEXT_TELEMETRY_DISABLED=1
ENV NODE_ENV=production

RUN corepack enable pnpm && pnpm run build

# 3. Production runner stage: Minimal attack surface & non-root execution
FROM base AS runner
WORKDIR /app

ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"

# DevSecOps: Create isolated non-root user (UID 1001)
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

# Set correct permissions for Next.js standalone cache
RUN mkdir .next
RUN chown nextjs:nodejs .next

# Copy standalone build and static assets
COPY --from=builder --chown=nextjs:nodejs /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1
CMD ["node", "server.js"]

Nasıl Kullanılır? (3 Adımda Canlıya Alma)

Üretilen Dockerfile ve .dockerignore dosyalarını projenizin kök dizinine kaydedin.
docker-compose.yml ve .env.example dosyalarını ekleyip cp .env.example .env ile ortam değişkenlerinizi ayarlayın.
Terminalde docker compose up -d --build komutunu çalıştırarak tüm sistemi ayağa kaldırın.

Modern Konteyner Mimarisi, Dockerfile Optimizasyonu ve DevSecOps Kılavuzu

Günümüz bulut bilişim ekosisteminde (Kubernetes, AWS ECS, Google Cloud Run, Fly.io, Coolify ve Dokploy) konteynerlerin boyutu, açılış hızı (cold-start) ve güvenlik sertleştirmesi doğrudan altyapı maliyetlerini ve servis kesintisizliğini belirler. Dockerfile & Docker Compose Builder; Next.js 15 Standalone, Python FastAPI (uv), Node.js, Go, Bun, Rust ve .NET 9 mimarileri için çok aşamalı (multi-stage) derleme standartlarında, güvenliği zırhlandırılmış ve orkestrasyonu hazır konfigürasyonlar üretir.

1. Multi-Stage (Çok Aşamalı) Derlemenin Anatomisi ve Katman Önbellekleme

Geleneksel tek aşamalı (single-stage) Dockerfile dosyalarında, kaynak kodun derlenebilmesi için gereken tüm ağır derleyiciler (C/C++ toolchain, TypeScript derleyicisi, Cargo, Go derleyicisi, pip build araçları) son imajda kalır. Bu durum 1 GB'ı aşan şişkin imajlara ve yüzlerce gereksiz güvenlik açığına (CVE) yol açar.

Multi-stage mimaride süreç aşamalara bölünür:

Dependencies (Bağımlılık) Aşaması: Yalnızca package.json veya pyproject.toml kopyalanarak paketler kurulur. Böylece kaynak kod her değiştiğinde bağımlılıklar baştan indirilmez, Docker layer cache kullanılır.
Builder (Derleme) Aşaması: Kod derlenir (ör. next build veya cargo build --release) ve statik çıktılar hazırlanır.
Runner (Üretim) Aşaması: Yalnızca minimal Alpine veya Debian-slim çalışma zamanı kullanılır. Yalnızca çalışması gereken tek bir binary veya izole sunucu dosyası kopyalanır.

2. Next.js 15+ App Router ve Standalone Modu

Next.js projelerinde standart bir node_modules klasörü kolaylıkla 800 MB - 1.2 GB boyutuna ulaşabilir. next.config.js içine output: "standalone" eklendiğinde, Next.js yalnızca sayfalarda kullanılan gerçek paketleri tespit eder (tree-shaking) ve bağımsız bir server.js oluşturur. Bu sayede üretim imajı yaklaşık 85 MB seviyesine iner.

3. DevSecOps: Non-Root Kullanıcı ve Container Breakout Önleme

Varsayılan olarak Docker konteynerleri root (UID 0) yetkisiyle başlar. Uygulamanızda meydana gelebilecek bir uzaktan kod yürütme (Remote Code Execution - RCE) açığında, saldırgan ana makinenin (host) çekirdeğine doğrudan root ayrıcalığıyla erişebilir. Aracımız tarafından otomatik eklenen USER nextjs veya USER appuser (UID 1001) direktifi, konteyner izolasyonunu en yüksek güvenlik seviyesine taşır.

4. Docker Compose v2 ve condition: service_healthy Mekanizması

Eski Docker Compose sürümlerinde yer alan standart depends_on: [postgres] tanımı yalnızca veritabanı konteynerinin başlatıldığını kontrol eder; veritabanının soketleri açıp sorgu kabul etmeye hazır olduğunu doğrulamaz. Bu durum uygulamanın "Connection refused" hatasıyla çökmesine (crashloop) neden olur.

Aracımızın ürettiği Docker Compose v2 şablonu, PostgreSQL için pg_isready, Redis için redis-cli ping, MongoDB için mongosh ping sağlık kontrollerini tanımlar ve ana uygulamayı condition: service_healthy ile kilitler.

5. Python Konteynerlerinde Devrim: Astral 'uv' ile Hızlandırılmış Derleme

FastAPI ve Flask mikroservislerinde geleneksel pip install -r requirements.txt komutları uzun süren bağımlılık çözümlemeleri nedeniyle CI/CD sürelerini uzatır. Astral tarafından geliştirilen Rust tabanlı uv, paket kurulumlarını 10 ila 100 kat hızlandırır. Konfigüratörümüz, Python seçildiğinde uv pip install --system komutlarıyla optimize edilmiş derleme katmanını otomatik hazırlar.

6. Karşılaştırma: Standart Dockerfile vs. Optimize Multi-Stage

Metrik / Kriter	Standart Tek Aşamalı Dockerfile	Optimize Multi-Stage (Aracımız)
Next.js İmaj Boyutu	~1.2 GB - 1.5 GB	~85 MB - 110 MB (%92 Tasarruf)
Go / Rust Binary Boyutu	~800 MB (SDK dahil)	~15 MB - 25 MB (Scratch / Alpine)
Güvenlik Profili	Root Kullanıcı (UID 0, Yüksek Risk)	Non-Root (appuser / nextjs UID 1001)
Veritabanı Çökme Koruması	Yok (Hemen başlar ve çöker)	Otomatik service_healthy Senkronizasyonu
İmaj İndirme (Pull) Süresi	45 - 90 saniye	2 - 5 saniye (Instant Startup)

7. Diğer Geliştirici Araçlarıyla Birlikte Kullanım

Konteynerize ettiğiniz uygulamanızın API uçlarını modern fetch isteklerine dönüştürmek için cURL to Modern Fetch aracımızı kullanabilir; veritabanı sorgularınızı ve index yapılarınızı optimize etmek için AI SQL Optimizer eklentimizden yararlanabilirsiniz. AI kodlama editörleri için standart kurallar üretmek isterseniz .cursorrules Generator aracımızı inceleyebilirsiniz.

İmajın tamamını indirmeden konteyner başlatmayı Docker lazy loading rehberi yazısında eStargz ve SOCI üzerinden anlattım.

Blog · Konular · SSS