Docker + NVIDIA Container Toolkit Kurulum: Kiralanan GPU'da Pratik Rehber

Docker + NVIDIA Container Toolkit Neden Kritik?

Kiralanan bir GPU sunucuda en sık yapılan hata, host'a doğrudan PyTorch/CUDA kurup sürümlere saplanmaktır. Docker + NVIDIA Container Toolkit yaklaşımı, sürücü ile framework'ü ayırır: host'ta yalnızca NVIDIA driver kalır; CUDA runtime, cuDNN ve PyTorch container image içinde gelir. Bu sayede aynı A100 veya H100 instance'ında bir projede CUDA 12.1, diğerinde 12.4 çalıştırabilirsiniz.

Bu rehber, Türkiye'de kiralanan Ubuntu GPU sunucularda pratik kurulum adımlarını, doğrulama komutlarını, PyTorch/CUDA image seçimini ve üretimde sık görülen hataları kapsar. Genel Docker GPU kullanımına dair kısa bir özet için Docker ile GPU kullanımı yazısına da bakabilirsiniz; burada kurulum ve troubleshooting derinliğine odaklanıyoruz.

Mimari: Host Driver vs Container CUDA

NVIDIA'nın GPU container modeli şu ayrımı yapar:

1. Host: NVIDIA driver (nvidia-smi burada çalışır)
2. NVIDIA Container Toolkit: Docker'a GPU cihazlarını, kütüphaneleri ve capability'leri enjekte eder
3. Container image: CUDA toolkit/runtime + uygulama (PyTorch, TensorFlow, özel kod)

Kritik kural: container içindeki CUDA sürümü, host driver'ın desteklediği maksimum CUDA sürümünden yüksek olmamalıdır. Driver yeterince yeniyse eski CUDA image'ları genelde sorunsuz çalışır; tersi (çok yeni CUDA + eski driver) "CUDA driver version is insufficient" hatasına yol açar.

AI eğitimi ve LLM fine-tuning işlerinde bu ayrım, ekip içi ortam tutarlılığını ve geri alma (rollback) hızını doğrudan etkiler.

Önkoşullar (Kiralanan Sunucuda Kontrol)

Kuruluma başlamadan önce SSH ile instance'a bağlanıp şu kontrolleri yapın.

1) GPU ve driver görünür mü?

nvidia-smi
uname -r
lsb_release -a

nvidia-smi GPU adını, driver sürümünü ve CUDA Version satırını gösterir. Buradaki "CUDA Version", host'ta yüklü full CUDA toolkit sürümü değil; driver'ın desteklediği maksimum CUDA bilgisidir. Örneğin CUDA Version: 12.4 görüyorsanız container'da 12.4 ve altı image'lar güvenli adaydır.

Driver yoksa veya GPU görünmüyorsa toolkit kurmak işe yaramaz. Çoğu kiralık GPU image'ında driver hazır gelir; yoksa sağlayıcı dokümantasyonundaki driver paketini kurun veya destekten image değişimi isteyin. İstanbul lokasyonlu düşük gecikmeli senaryolar için İstanbul GPU kiralama sayfasındaki altyapı notlarına bakabilirsiniz.

2) Docker kurulu ve çalışan mı?

docker --version
sudo systemctl status docker --no-pager

Docker yoksa Ubuntu 22.04 için resmi Docker CE kurulumunu tercih edin (distro'nun eski docker.io paketi yerine). Kısa özet:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker $USER

usermod sonrası oturumu kapatıp açın (veya newgrp docker). Root'suz docker run için bu adım zorunludur.

3) Kernel / nouveau çakışması

Nadiren nouveau açık kalır ve NVIDIA modülleri yüklenemez. Belirti: nvidia-smi "couldn't communicate with the NVIDIA driver" der.

lsmod | grep -E 'nvidia|nouveau'
cat /proc/driver/nvidia/version

nouveau görürseniz blacklist + reboot gerekir; production kiralık image'larda bu durum seyrektir ama custom ISO'larda çıkar.

NVIDIA Container Toolkit Kurulumu (Ubuntu 22.04)

Aşağıdaki adımlar NVIDIA'nın güncel apt deposu yaklaşımına uygundur. Komutları sırayla çalıştırın.

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

Kurulumdan sonra Docker runtime'ını yapılandırın:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Bu komut /etc/docker/daemon.json içine NVIDIA runtime bilgisini ekler. Elle düzenleme yapacaksanız yedek alın; JSON sözdizimi hatası Docker'ı ayağa kalkamaz hale getirir.

Hızlı doğrulama: CUDA container + nvidia-smi

docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

Beklenen sonuç: host'takiyle aynı GPU listesi. Bu komut başarılıysa toolkit doğru bağlanmıştır. Başarısızsa aşağıdaki "Yaygın Hatalar" bölümüne geçin — çoğu sorun burada çözülür.

Eski sözdizimi (--runtime=nvidia) hâlâ çalışabilir; modern Docker'da önerilen bayrak --gpus'tır.

PyTorch ve CUDA Image Seçimi

Kurulum bittikten sonra asıl verim, doğru image tag'inde gizlidir. PyTorch GPU kurulum rehberi bare-metal/conda senaryolarını anlatır; container'da ise resmi tag'ler tercih edilmelidir.

Resmi PyTorch image

docker run --rm -it --gpus all \
  -v "$PWD":/workspace -w /workspace \
  pytorch/pytorch:2.4.0-cuda12.1-cudnn9-runtime \
  python -c "import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.get_device_name(0))"

Çıktıda True ve GPU adı görünmelidir. runtime tag'i eğitim/inference için yeterlidir; özel CUDA extension derleyecekseniz devel veya nvidia/cuda:*-devel tabanlı custom Dockerfile kullanın.

NVIDIA CUDA base / runtime / devel farkı

Gereksiz devel image'ları disk ve pull süresini şişirir. Saatlik fiyatlandırma modelinde ilk pull dakikaları da faturalanır; bu yüzden image'ı bir kez çekip local cache'te tutmak veya private registry kullanmak maliyet dostudur.

Örnek Dockerfile (tekrarlanabilir eğitim ortamı)

FROM pytorch/pytorch:2.4.0-cuda12.1-cudnn9-runtime

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["python", "train.py"]

docker build -t my-train:0.1 .
docker run --rm --gpus all \
  -v /data/datasets:/data:ro \
  -v /data/checkpoints:/checkpoints \
  my-train:0.1

Dataset'i image'a gömmeyin; volume mount kullanın. Checkpoint'leri host path'e yazmak, container silinse bile modeli korur — spot benzeri kesintilerde hayati önem taşır (spot stratejisi).

Pratik Workflow: Jupyter, Port ve Veri

Jupyter Lab container

docker run --rm -it --gpus all \
  -p 8888:8888 \
  -v "$PWD":/workspace -w /workspace \
  pytorch/pytorch:2.4.0-cuda12.1-cudnn9-runtime \
  bash -lc "pip install -q jupyterlab && jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root"

Güvenlik: Jupyter'ı doğrudan 0.0.0.0'a açmak yerine SSH tunnel tercih edin:

ssh -L 8888:127.0.0.1:8888 kullanici@sunucu-ip

Daha geniş Jupyter pratikleri için Jupyter bulut GPU rehberi faydalıdır.

Compose ile kalıcı stack

services:
  train:
    image: pytorch/pytorch:2.4.0-cuda12.1-cudnn9-runtime
    working_dir: /workspace
    volumes:
      - ./:/workspace
      - /data:/data
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    command: python train.py

Compose V2'de GPU rezervasyonu deploy.resources ile tanımlanır; bazı ortamlarda eski runtime: nvidia hâlâ kullanılır. Kiralanan sunucuda hangisinin geçerli olduğunu docker compose up ile doğrulayın.

Multi-GPU Container Kullanımı

Tek container'a tüm GPU'ları vermek:

docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi -L

Belirli GPU'ları izole etmek (paralel deneyler):

docker run --rm --gpus '"device=0,1"' nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi -L
docker run --rm --gpus '"device=2,3"' nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi -L

Bu model, aynı RTX 4090 veya 4x A100 node üzerinde iki bağımsız job çalıştırmayı kolaylaştırır. Distributed Data Parallel (DDP) için container içinde torchrun kullanırsınız; NCCL/NVLink detayları için multi-GPU eğitim rehberi ile birlikte okuyun.

Dikkat: İki container aynı GPU'yu paylaşırsa VRAM thrashing ve OOM kaçınılmazdır. Cihaz atamasını bilinçli yapın.

Yaygın Hatalar ve Çözümleri

1) `could not select device driver "" with capabilities: [[gpu]]`

Anlamı: Docker, NVIDIA runtime'ı görmüyor.

Çözüm:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
docker info | grep -i runtime

Runtimes satırında nvidia görünmelidir.

2) `NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver`

Host'ta da nvidia-smi bozuktur. Toolkit değil, driver/modül sorunudur. dmesg | tail, reboot ve doğru driver paketi kontrol edilir. Container'ı suçlamayın.

3) `CUDA driver version is insufficient for CUDA runtime version`

Container CUDA'sı, host driver'dan daha yeni. Ya daha eski bir image tag'i seçin ya da host driver'ı yükseltin (kiralık sunucuda genelde image/tag değiştirmek daha güvenlidir).

4) `docker: Error response from daemon: could not find nvidia-container-runtime`

Paket eksik veya PATH/config bozuk. Yeniden kurun:

sudo apt-get install --reinstall -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

5) GPU görünüyor ama PyTorch `False` dönüyor

Sık nedenler: CPU-only wheel kurulmuş olması, yanlış image, veya CUDA_VISIBLE_DEVICES boş/yanlış.

python -c "import torch; print(torch.version.cuda, torch.cuda.is_available())"
echo $CUDA_VISIBLE_DEVICES

Container'ı pytorch/pytorch:*-cuda* tag'inden yeniden başlatın; host'a pip install torch ile CPU wheel kurup volume'a bulaştırmayın.

6) Permission denied / socket errors

Kullanıcı docker grubunda değilse veya rootless Docker + toolkit uyumsuzluğu varsa görülür. Standart kiralık Ubuntu'da rootful Docker + toolkit en az sürtünmeli yoldur.

7) Disk doldu (image layer birikimi)

Uzun süren eğitim node'larında eski tag'ler disk doldurur; GPU saati çalışırken disk full olursa checkpoint yazımı başarısız olur.

docker system df
docker image prune -a

Dikkatli prune yapın; aktif tag'leri silmeyin.

daemon.json ve Runtime İnce Ayarı

nvidia-ctk runtime configure sonrasında tipik bir /etc/docker/daemon.json şöyle görünebilir:

{
  "runtimes": {
    "nvidia": {
      "path": "nvidia-container-runtime",
      "runtimeArgs": []
    }
  },
  "default-runtime": "nvidia"
}

default-runtime'ı nvidia yapmak, her docker run'da --gpus unutulsa bile bazı ortamlarda GPU enjeksiyonunu kolaylaştırır; ancak tüm container'lara GPU bağlamayı istemiyorsanız default'u değiştirmeyin — yalnızca --gpus kullanan işlere kaynak verin. JSON'u elle düzenledikten sonra mutlaka sudo systemctl restart docker ve docker run --rm --gpus all ... nvidia-smi ile doğrulayın.

Log seviyesini yükseltmek için toolkit tarafında nvidia-container-runtime debug log'ları açılabilir; "device not found" gibi belirsiz hatalarda host dmesg ile birlikte bakmak teşhisi hızlandırır.

CI/CD ve Registry Pratiği

Ekip büyüdükçe herkesin laptop'undan docker build yapmak yerine private registry (Harbor, GHCR self-hosted mirror veya sağlayıcı registry) kullanın. Pipeline önerisi:

1. CI'da CPU runner ile image build + unit test
2. GPU smoke job'unda kiralanan kısa ömürlü instance'ta torch.cuda.is_available() ve 1-adımlık forward pass
3. Başarılı tag'i myregistry/train:git-sha olarak push
4. Eğitim node'unda yalnızca pull + run

Bu akış, startup GPU ipuçları ile uyumlu şekilde deneme maliyetini düşürür: GPU saati yalnızca gerçek eğitim ve kısa smoke test için yanar. Büyük base image'ları gece önceden node'a pull etmek de sabah kickoff süresini kısaltır.

MIG, MPS ve Paylaşımlı Kullanım (İleri)

A100/H100 gibi kartlarda MIG (Multi-Instance GPU) ile tek fiziksel GPU'yu izole dilimlere bölebilirsiniz. Container tarafında her dilim ayrı cihaz gibi görünür; --gpus cihaz UUID'si ile bağlanır. Küçük inference servislerini aynı kartta izole etmek istiyorsanız MIG değerlidir; tam kapasite eğitimde genelde MIG kapalı tutulur.

MPS (Multi-Process Service) ise süreçler arası GPU paylaşımını yumuşatır ama güçlü izolasyon sunmaz. Üretimde komşu işlerin birbirini bozmasını istemiyorsanız cihaz ataması veya MIG tercih edin; "herkes aynı GPU'ya dokunsun" yaklaşımı kiralık ortamda hem debug'ı hem fatura kontrolünü zorlaştırır.

Performans ve Maliyet İpuçları (Kiralık GPU)

1. Image'ı önceden pull edin — eğitim başı bekleme süresini kısaltır.
2. Dataset'i NVMe'de tutun — network volume üzerinde DataLoader darboğazı yaratır; CUDA optimizasyonu yazısındaki prefetch ipuçları container içinde de geçerlidir.
3. Idle container bırakmayın — --gpus ile ayakta duran Jupyter, GPU'yu rezerve edip saatlik fatura üretir.
4. Tag'leri pin'leyin — latest yerine 2.4.0-cuda12.1-... kullanın; tekrarlanabilirlik ve debug için şarttır.
5. Doğru GPU sınıfı seçin — container sorunu çözmez; VRAM yetersizse L40S veya A100'e geçin. Inference odaklı işler için inference hizmeti sayfasındaki senaryolara bakın.
6. Çoklu deney = cihaz izolasyonu — device=0 / device=1 ile paralel job, tek job'un tüm kartı kilitlemesinden ucuz olabilir.
7. shm-size artırın — DataLoader num_workers > 0 iken varsayılan /dev/shm (64MB) yetmez; --shm-size=4g veya daha yüksek verin, aksi halde bus error görürsünüz.
8. IPC ve ulimit — bazı NCCL senaryolarında --ipc=host veya uygun ulimit gerekir; güvenlik ile performans arasında bilinçli tercih yapın.

Güvenlik Notları

• Container root olarak çalışıyorsa host volume mount'ları güçlü yetki demektir; üretimde non-root user düşünün.
• Secret'ları image layer'ına yazmayın; -e veya Docker secrets / env file kullanın.
• Jupyter token'ını log'a düşürmeyin; SSH tunnel + güçlü token kombinasyonu tercih edin.
• KVKK kapsamındaki veri setlerinde yurt dışı registry'ye veri push etmeyin; modeli ve veriyi Türkiye lokasyonlu depolamada tutun (KVKK ve GPU kiralama).

Kontrol Listesi (Go-Live)

1. Host nvidia-smi temiz
2. nvidia-container-toolkit kurulu
3. nvidia-ctk runtime configure + Docker restart yapıldı
4. docker run --gpus all nvidia/cuda:... nvidia-smi başarılı
5. PyTorch image'da torch.cuda.is_available() == True
6. Dataset/checkpoint volume'ları bağlandı
7. Idle timeout / durdurma alışkanlığı net

Bu liste yeşilse, kiralanan sunucuda container tabanlı GPU workflow'unuz üretime hazır demektir. Genel GPU seçimi ve bütçe için GPU kiralama rehberi 2026 ve fiyatlandırma sayfalarını birlikte kullanın.

Sonuç

Docker + NVIDIA Container Toolkit, kiralık GPU'da "çalışır ortam" ile "tekrarlanabilir ortam" arasındaki farktır. Host'ta driver'ı sağlam tutun, toolkit'i bir kez doğru yapılandırın, CUDA/PyTorch sürümlerini image tag'leriyle sabitleyin. Bundan sonrası model ve veri mühendisliğidir — altyapı sürtünmesi değil.

Yeni bir instance aldığınızda bu yazıdaki doğrulama komutlarını ilk 10 dakikada çalıştırmak, saatler süren yanlış sürücü/framework avını engeller.