ubuntu-bare-metal/manual-tutorial/03-nvidia-container-toolkit.md

03 — NVIDIA Container Toolkit

Cel rozdziału: skonfigurować Docker tak, aby kontenery miały dostęp do GPU NVIDIA (RTX 3090 Ti) — fundament pod vLLM i ComfyUI.

Szacowany czas: 10–15 minut

Wymagania: ukończone rozdziały 01 i 02

---

Spis treści

1. Weryfikacja punktu startowego
2. Co robi NVIDIA Container Toolkit
3. Instalacja
4. Konfiguracja runtime Docker
5. Test GPU w kontenerze
6. Składnia GPU dla Compose (podgląd)
7. Weryfikacja
8. Troubleshooting
9. Czego nie robimy w tym kroku
10. Następny krok

---

1. Weryfikacja punktu startowego

# sterownik NVIDIA z rozdziału 02
nvidia-smi

# Docker z rozdziału 01
docker --version
docker ps

# toolkit jeszcze niezainstalowany
which nvidia-ctk 2>/dev/null || echo "nvidia-ctk: not installed (expected)"

Oczekiwany wynik:

• nvidia-smi pokazuje RTX 3090 Ti, driver 595.x
• Docker działa (docker ps bez błędów)
• nvidia-ctk niedostępne

---

2. Co robi NVIDIA Container Toolkit

Bez tego pakietu Docker nie widzi GPU — kontener uruchomi się, ale bez akceleracji CUDA.

Toolkit dostarcza:

Komponent	Rola
nvidia-container-toolkit	Integracja GPU z container runtime
nvidia-ctk	CLI do konfiguracji (Docker, containerd)
libnvidia-container	Biblioteka montująca sterownik i urządzenia GPU do kontenera

Jak to działa:

flowchart LR
    host["Host: nvidia-driver + nvidia-smi"]
    docker["Docker Engine"]
    toolkit["NVIDIA Container Toolkit"]
    container["Kontener vLLM / ComfyUI"]

    host --> toolkit
    docker --> toolkit
    toolkit --> container

Kontener nie potrzebuje własnego sterownika NVIDIA — dziedziczy go z hosta przez toolkit. Obraz musi mieć tylko biblioteki CUDA kompatybilne z wersją sterownika.

Uwaga: Nie instalujemy przestarzałego nvidia-docker2 — został zastąpiony przez Container Toolkit.

---

3. Instalacja

3.1 Dodanie repozytorium NVIDIA

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

3.2 Instalacja pakietu

sudo apt update
sudo apt install -y nvidia-container-toolkit

3.3 Sprawdzenie wersji

nvidia-ctk --version
dpkg -l | grep nvidia-container

---

4. Konfiguracja runtime Docker

Toolkit musi zarejestrować runtime NVIDIA w Dockerze:

sudo nvidia-ctk runtime configure --runtime=docker

Ta komenda modyfikuje /etc/docker/daemon.json — dodaje konfigurację runtime nvidia, zachowując istniejące ustawienia (np. rotację logów z rozdziału 01).

Sprawdź wynik:

cat /etc/docker/daemon.json

Oczekiwana struktura (przykład — Twoja może wyglądać nieco inaczej):

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "50m",
    "max-file": "3"
  },
  "runtimes": {
    "nvidia": {
      "args": [],
      "path": "nvidia-container-runtime"
    }
  }
}

Zrestartuj Docker:

sudo systemctl restart docker

Sprawdź, że daemon wstał:

sudo systemctl status docker --no-pager

---

5. Test GPU w kontenerze

5.1 Podstawowy test — nvidia-smi w kontenerze

docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu24.04 nvidia-smi

Oczekiwany wynik:

• Ten sam GPU: NVIDIA GeForce RTX 3090 Ti
• Driver Version: 595.x (z hosta)
• Brak błędów could not select device driver

Pierwsze uruchomienie pobierze obraz CUDA (~100–200 MB) — to normalne.

5.2 Test z jednym GPU (explicit)

Na tym serwerze jest jedna karta NVIDIA, ale warto od razu testować jawne przypisanie:

docker run --rm --gpus '"device=0"' nvidia/cuda:12.6.0-base-ubuntu24.04 nvidia-smi -L

Oczekiwane: GPU 0: NVIDIA GeForce RTX 3090 Ti

5.3 Test bez GPU (kontrolny)

docker run --rm nvidia/cuda:12.6.0-base-ubuntu24.04 nvidia-smi

Oczekiwane: błąd — kontener bez --gpus nie widzi GPU. To potwierdza, że GPU nie jest przypadkowo dostępne dla każdego kontenera.

---

6. Składnia GPU dla Compose (podgląd)

W rozdziałach 04 (vLLM) i 05 (ComfyUI) użyjemy docker compose z GPU. Podgląd składni:

services:
  vllm:
    image: vllm/vllm-openai:latest
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

Alternatywnie (prostsza składnia, działa w Compose v2):

services:
  comfyui:
    image: yanwk/comfyui-boot:latest
    gpus: all

Na razie nie twórz tych plików — to tylko podgląd na przyszłość.

---

7. Weryfikacja

Checklist

• nvidia-ctk --version zwraca wersję
• /etc/docker/daemon.json zawiera runtime nvidia
• docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu24.04 nvidia-smi działa
• W kontenerze widać RTX 3090 Ti (24 GB)
• docker run bez --gpus nie widzi GPU (kontrolny test)
• Docker z rozdziału 01 nadal działa (hello-world OK)

Szybki test końcowy

docker run --rm hello-world
docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu24.04 nvidia-smi

---

8. Troubleshooting

8.1 could not select device driver "" with capabilities: [[gpu]]

Przyczyna: Runtime NVIDIA nie skonfigurowany lub Docker nie zrestartowany.

Rozwiązanie:

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

8.2 nvidia-smi działa na hoście, ale nie w kontenerze

Diagnostyka:

# na hoście
nvidia-smi

# sprawdź runtime w docker info
docker info 2>/dev/null | grep -A5 -i runtime

# logi toolkit
sudo journalctl -u docker --no-pager -n 30

Rozwiązanie:

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

8.3 Konflikt w daemon.json

Objaw: systemctl restart docker → failed po edycji daemon.json.

Rozwiązanie:

# walidacja JSON
python3 -m json.tool /etc/docker/daemon.json

# jeśli błąd składni — przywróć minimalną konfigurację i skonfiguruj ponownie
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "50m",
    "max-file": "3"
  }
}
EOF

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

8.4 apt update — konflikt Signed-By

Objaw: Błąd repozytorium przy apt update po dodaniu NVIDIA repo.

Rozwiązanie:

# usuń i dodaj repo ponownie (sekcja 3.1)
sudo rm /etc/apt/sources.list.d/nvidia-container-toolkit.list
# ... powtórz kroki 3.1 i 3.2

8.5 Obraz CUDA — pull failed / timeout

# test połączenia z registry
docker pull nvidia/cuda:12.6.0-base-ubuntu24.04

# alternatywny lekki obraz testowy
docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi

8.6 CUDA Version w kontenerze vs na hoście

Na hoście nvidia-smi może pokazywać CUDA 13.2, a obraz testowy CUDA 12.6 — to normalne. Kontener używa sterownika hosta; wersja CUDA w obrazie to maksymalna wersja bibliotek w kontenerze, nie sterownik.

---

9. Czego nie robimy w tym kroku

Element	Rozdział
vLLM	04
ComfyUI	05
Pobieranie modeli LLM	04
CUDA Toolkit na hoście	niepotrzebne
Firewall	06
Katalog /data na modele	później

---

10. Następny krok

Po przejściu checklisty z sekcji 7:

1. Zgłoś w rozmowie z Cursorem, że krok 03 jest gotowy (lub opisz problemy).
2. Przejdź do rozdziału 03b — Narzędzia bazowe, a następnie 04 — Dysk + vLLM.

---

Podsumowanie wykonanych zmian

Po ukończeniu tego rozdziału na serwerze powinno być:

• Zainstalowany nvidia-container-toolkit
• Skonfigurowany runtime NVIDIA w Dockerze
• Działający docker run --gpus all z widoczną RTX 3090 Ti
• Gotowa infrastruktura pod vLLM i ComfyUI w kontenerach