Initial import: bare-metal stacks, Server UI, GPU fan, tutorials.

Infrastructure configs for GMKtec K11 (Docker, vLLM, LocalAI, ComfyUI, control-plane, gpu-fan agent, Server UI with CLI/file explorer/GPU fan curve). Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-05 12:02:04 +00:00
commit 359afb3a59
153 changed files with 18169 additions and 0 deletions
@@ -0,0 +1,362 @@
+# 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