16 Kasım 2026 PazartesiRSS

DevelopmentYazılım

Docker Multi-Stage Build ile Küçük ve Güvenli İmajlar

Aziz Özdemiroğlu

Bir Node.js uygulamasının Docker imajı 1,2 GB da olabilir, 150 MB da. Aradaki fark yalnızca disk alanı değil: daha büyük imaj daha yavaş dağıtım, daha uzun açılış ve daha geniş saldırı yüzeyi demek. Bu rehberde çok aşamalı (multi-stage) build'lerle küçük, hızlı ve güvenli imajlar üretmeyi; katman önbelleğini doğru kullanmayı ve imajınızı yayına almadan önce taramayı adım adım anlatıyoruz.

Kısaca

  • Çok aşamalı build: Derleme araçları ilk aşamada kalır, son imaja yalnızca çalışmak için gerekenler kopyalanır.
  • Katman sırası önbelleği belirler: Önce bağımlılık dosyalarını kopyalayıp kurun, kaynak kodu en son kopyalayın.
  • Root olmayan kullanıcı, .dockerignore, sabitlenmiş taban imaj ve sağlık kontrolü (healthcheck) temel hijyen kurallarıdır.
  • Sırları asla ARG/ENV ile imaja gömmeyin. BuildKit'in --mount=type=secret özelliğini kullanın.
  • Yayından önce Trivy veya Grype ile tarayın, SBOM üretin.

Çok aşamalı build neden işe yarar?

Tek aşamalı bir Dockerfile'da derleyiciler, devDependencies, test araçları ve önbellekler son imajda kalır. Çok aşamalı build'de her FROM yeni bir aşama başlatır ve son aşamaya yalnızca COPY --from=... ile seçtiğiniz dosyalar gelir.

[deps] npm ci (tüm bağımlılıklar)  ──►  [build] npm run build  ──►  [runner] yalnızca çıktı + üretim bağımlılıkları
      ~900 MB                              ~1 GB                         ~150–250 MB

Örnek 1: Node.js / Next.js uygulaması

# syntax=docker/dockerfile:1

# --- 1. Bağımlılıklar ---
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci

# --- 2. Derleme ---
FROM node:22-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED=1
RUN npm run build

# --- 3. Çalışma imajı ---
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production NEXT_TELEMETRY_DISABLED=1 PORT=3000 HOSTNAME=0.0.0.0

# Next.js "standalone" çıktısı yalnızca gereken node_modules'ü içerir
COPY --from=builder --chown=node:node /app/.next/standalone ./
COPY --from=builder --chown=node:node /app/.next/static ./.next/static
COPY --from=builder --chown=node:node /app/public ./public

USER node
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
  CMD wget -qO- http://127.0.0.1:3000/api/health || exit 1
CMD ["node", "server.js"]

Next.js için next.config içinde output: "standalone" ayarı gerekir. Bu sayede son imaja tüm node_modules yerine yalnızca izlenen (traced) bağımlılıklar kopyalanır.

Örnek 2: Go uygulaması — "distroless" ile

Statik derlenen dillerde son imaj neredeyse boş olabilir:

# syntax=docker/dockerfile:1
FROM golang:1.25 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
COPY . .
RUN --mount=type=cache,target=/root/.cache/go-build \
    CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags="-s -w" -o /out/app ./cmd/app

FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/app /app
USER nonroot:nonroot
ENTRYPOINT ["/app"]

Distroless imajlarda kabuk (sh) ve paket yöneticisi yoktur. Saldırgan içeri girse bile kullanabileceği araç çok azdır. Hata ayıklama için :debug etiketli varyantları geçici olarak kullanabilirsiniz.

Katman önbelleğini doğru kullanmak

Docker her talimatı bir katman olarak önbelleğe alır. Bir katman değişirse sonraki tüm katmanlar yeniden oluşturulur.

Yanlış sıra Doğru sıra
COPY . . → RUN npm ci COPY package*.json ./ → RUN npm ci → COPY . .
Her kod değişikliğinde bağımlılıklar yeniden kurulur Bağımlılıklar yalnızca package-lock.json değişince kurulur

Ek hız için BuildKit önbellek bağlamaları (--mount=type=cache) paket yöneticisinin indirme önbelleğini build'ler arasında korur ve imaja eklemez.

.dockerignore: görünmez ama kritik

node_modules
.next
.git
.env*
*.log
coverage
Dockerfile*
docker-compose*.yml

.dockerignore olmadan COPY . . komutu .git geçmişinizi ve .env dosyalarınızı imaja kopyalayabilir. Bu hem boyutu şişirir hem de sır sızıntısına yol açar.

Sırları imaja gömmeyin

# YANLIŞ — token imaj geçmişinde kalır (docker history ile görülebilir)
ARG NPM_TOKEN
RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc && npm ci

# DOĞRU — sır yalnızca bu RUN süresince bağlanır, katmana yazılmaz
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci
docker build --secret id=npmrc,src=$HOME/.npmrc -t uygulama:1.0 .

Güvenlik hijyeni kontrol listesi

  • Taban imaj resmi ve minimal (alpine, slim, distroless)
  • Taban imaj sürümü sabit (node:22.x-alpine). Tekrarlanabilirlik için digest ile sabitleme (@sha256:...) daha da iyi
  • Son aşamada USER ile root olmayan kullanıcı
  • .dockerignore içinde .env, .git, node_modules
  • Sırlar --mount=type=secret ile, ARG/ENV ile değil
  • HEALTHCHECK tanımlı
  • Gereksiz paket yok (curl, git, derleyiciler son imajda değil)
  • Container çalışırken salt okunur dosya sistemi (read_only: true) ve cap_drop: [ALL] değerlendirildi
  • İmaj düzenli olarak yeniden derleniyor, böylece taban imaj güvenlik yamaları alınıyor

Yayından önce tarama ve SBOM

# Trivy ile güvenlik açığı taraması (yalnızca yüksek ve kritik)
trivy image --severity HIGH,CRITICAL --ignore-unfixed uygulama:1.0

# Grype alternatifi
grype uygulama:1.0 --fail-on high

# SBOM üretimi (CycloneDX formatında)
syft uygulama:1.0 -o cyclonedx-json > sbom.cdx.json

Bu komutları CI'da çalıştırıp kritik bulgu varsa build'i durdurmak, açıklı imajların üretime çıkmasını engeller.

Boyutu analiz etmek

docker images uygulama                 # toplam boyut
docker history uygulama:1.0            # katman katman boyut
dive uygulama:1.0                      # etkileşimli katman inceleme aracı

dive, hangi katmanın gereksiz dosyalar eklediğini (ör. silinmiş ama önceki katmanda kalmış önbellekler) görsel olarak gösterir.

Docker Compose ile çalışma zamanı sertleştirmesi

services:
  app:
    image: uygulama:1.0
    read_only: true
    tmpfs: [/tmp]
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    deploy:
      resources:
        limits: { memory: 512M, cpus: "1.0" }
    restart: unless-stopped

Sık yapılan hatalar ve çözümleri

Hata Belirti Çözüm
npm install kullanmak Her build'de farklı sürümler, tekrarlanamayan hatalar npm ci ve depoda package-lock.json
RUN apt-get update ile install'u ayrı satırlarda yazmak Eski paket listesi önbellekten gelir, kurulum başarısız olur RUN apt-get update && apt-get install -y --no-install-recommends ... && rm -rf /var/lib/apt/lists/*
Son aşamada devDependencies İmaj yüzlerce MB büyür, tarayıcı gereksiz bulgular üretir Standalone çıktı veya npm ci --omit=dev
latest etiketi Dün çalışan build bugün bozulur Sürüm veya digest ile sabitleme
Container'ı root ile çalıştırmak Kaçış (escape) durumunda host riski artar USER node / USER nonroot
Alpine'de glibc bağımlı ikili dosyalar not found gibi şaşırtıcı hatalar -slim (Debian) taban imaj veya statik derleme
Günlükleri dosyaya yazmak Container diski dolar Günlükleri stdout/stderr'e yazın, Docker toplasın

Alpine mi, slim mi, distroless mu?

  • Alpine (musl libc): En küçük boyut. Ama bazı yerel (native) modüller ve önceden derlenmiş ikili dosyalar glibc bekler. Ayrıca musl'a özgü sorunlar zaman zaman ortaya çıkar (Kasım 2026'daki OpenSSH "musl + PAM kapalı" açığı buna bir örnek).
  • Debian slim (glibc): Biraz daha büyük, ama uyumluluk sorunu en az olan seçenek. Çoğu ekip için güvenli varsayılan.
  • Distroless: Kabuk ve paket yöneticisi yok, saldırı yüzeyi en küçük. Hata ayıklama zorlaşır. Olgun CI/CD ve gözlemlenebilirlik altyapısı olan ekipler için ideal.

Sonuç

Çok aşamalı build, küçük ve güvenli imajın temelidir. Ama asıl fark doğru katman sırası, root olmayan kullanıcı, .dockerignore, gömülmemiş sırlar ve düzenli taramayla birlikte gelir. Mevcut bir Dockerfile'ınızı bu listeyle gözden geçirin. Çoğu projede imaj boyutunu yarıya indirmek ve tarama bulgularını ciddi oranda azaltmak bir saatlik iştir.

Kaynaklar

#Docker#Multi-Stage Build#Container Güvenliği#Distroless#Trivy#Next.js

Benzer Yazılar