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](01-system-update-and-docker.md) i [02](02-nvidia-driver.md)

---

## Spis treści

1. [Weryfikacja punktu startowego](#1-weryfikacja-punktu-startowego)
2. [Co robi NVIDIA Container Toolkit](#2-co-robi-nvidia-container-toolkit)
3. [Instalacja](#3-instalacja)
4. [Konfiguracja runtime Docker](#4-konfiguracja-runtime-docker)
5. [Test GPU w kontenerze](#5-test-gpu-w-kontenerze)
6. [Składnia GPU dla Compose (podgląd)](#6-składnia-gpu-dla-compose-podgląd)
7. [Weryfikacja](#7-weryfikacja)
8. [Troubleshooting](#8-troubleshooting)
9. [Czego nie robimy w tym kroku](#9-czego-nie-robimy-w-tym-kroku)
10. [Następny krok](#10-następny-krok)

---

## 1. Weryfikacja punktu startowego

```bash
# 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:**

```mermaid
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

```bash
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

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

### 3.3 Sprawdzenie wersji

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

---

## 4. Konfiguracja runtime Docker

Toolkit musi zarejestrować runtime NVIDIA w Dockerze:

```bash
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:

```bash
cat /etc/docker/daemon.json
```

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

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

Zrestartuj Docker:

```bash
sudo systemctl restart docker
```

Sprawdź, że daemon wstał:

```bash
sudo systemctl status docker --no-pager
```

---

## 5. Test GPU w kontenerze

### 5.1 Podstawowy test — `nvidia-smi` w kontenerze

```bash
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:

```bash
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)

```bash
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:

```yaml
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):

```yaml
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

```bash
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:**

```bash
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:**

```bash
# 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:**

```bash
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:**

```bash
# 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:**

```bash
# 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

```bash
# 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**](03b-system-tools.md), a następnie [**04 — Dysk + vLLM**](04-vllm-stack.md).

---

## 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