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/ENVile 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
USERile root olmayan kullanıcı -
.dockerignoreiçinde.env,.git,node_modules - Sırlar
--mount=type=secretile,ARG/ENVile değil -
HEALTHCHECKtanımlı - Gereksiz paket yok (
curl,git, derleyiciler son imajda değil) - Container çalışırken salt okunur dosya sistemi (
read_only: true) vecap_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




