ubuntu-bare-metal/manual-tutorial/02-nvidia-driver.md

# 02 — Sterowniki NVIDIA

> **Cel rozdziału:** zainstalować sterownik NVIDIA dla RTX 3090 Ti na headless serwerze Ubuntu 26.04, tak aby `nvidia-smi` działało na hoście przed konfiguracją GPU w Dockerze.

**Szacowany czas:** 15–30 minut (zależy od pobierania pakietów i ewentualnego DKMS)

**Wymagania:** ukończony rozdział [01 — Aktualizacja systemu i Docker CE](01-system-update-and-docker.md)

---

## Spis treści

1. [Weryfikacja punktu startowego](#1-weryfikacja-punktu-startowego)
2. [Wybór sterownika](#2-wybór-sterownika)
3. [Instalacja sterownika](#3-instalacja-sterownika)
4. [Restart i pierwsze uruchomienie](#4-restart-i-pierwsze-uruchomienie)
5. [Konfiguracja serwerowa (opcjonalna)](#5-konfiguracja-serwerowa-opcjonalna)
6. [Weryfikacja](#6-weryfikacja)
7. [Troubleshooting](#7-troubleshooting)
8. [Czego nie robimy w tym kroku](#8-czego-nie-robimy-w-tym-kroku)
9. [Następny krok](#9-następny-krok)

---

## 1. Weryfikacja punktu startowego

```bash
# Docker z rozdziału 01 — musi działać
docker --version
docker ps

# GPU widoczne w PCI
lspci | grep -i "nvidia"

# nvidia-smi jeszcze nie działa — to normalne
nvidia-smi 2>/dev/null || echo "nvidia-smi: not available (expected)"

# lista dostępnych sterowników
sudo ubuntu-drivers devices
```

**Oczekiwany wynik:**

- RTX 3090 Ti (`GA102`) widoczna w `lspci`
- `nvidia-smi` niedostępne
- `ubuntu-drivers` pokazuje m.in. `nvidia-driver-595-open` jako **recommended**

Sprawdź też Secure Boot (wpływa na DKMS):

```bash
mokutil --sb-state 2>/dev/null || echo "mokutil not available"
```

Na tym serwerze Secure Boot jest wyłączony — nie będzie promptu MOK przy instalacji.

---

## 2. Wybór sterownika

Dla **headless serwera AI** (vLLM + ComfyUI, bez monitora) rekomendujemy wariant **server + open kernel modules**:

| Wariant | Pakiet | Kiedy użyć |
|---------|--------|------------|
| **Rekomendowany** | `nvidia-driver-595-server-open` | Serwer compute, bez GUI, nowoczesne moduły open |
| Alternatywa | `nvidia-driver-595-open` | Jeśli server-open sprawia problemy |
| Nie używamy | `nouveau` | Sterownik open-source — za wolny do AI |

**Dlaczego server-open, a nie desktop `595-open`?**

- Wariant **server** nie ciągnie zbędnych zależności od display managera
- Wariant **open** to aktualna rekomendacja Ubuntu 26.04 dla nowoczesnych GPU
- Sterownik pochodzi z repozytorium Ubuntu (`restricted`) — aktualizuje się przez `apt upgrade` i przeżywa upgrade kernela (DKMS / prebuilt modules)

**Uwaga:** Na hoście **nie instalujemy** pełnego CUDA Toolkit. Kontenery vLLM/ComfyUI dostarczą własne biblioteki CUDA — w rozdziale 03 dodamy tylko NVIDIA Container Toolkit.

**Dual GPU:** W tym systemie jest też iGPU AMD (HawkPoint). Do workloadów AI używamy wyłącznie NVIDIA:

```bash
# zapisz na później — używane w compose stackach
export CUDA_VISIBLE_DEVICES=0
```

---

## 3. Instalacja sterownika

### 3.1 Pakiety pomocnicze

```bash
sudo apt update
sudo apt install -y ubuntu-drivers-common
```

### 3.2 Instalacja sterownika server-open (rekomendowana)

```bash
sudo ubuntu-drivers install --gpgpu nvidia:595-server-open
```

Flaga `--gpgpu` filtruje sterowniki pod obciążenia compute (bez GUI).

Jeśli powyższa komenda zgłosi brak pakietu, użyj bezpośredniej instalacji apt:

```bash
sudo apt install -y nvidia-driver-595-server-open
```

### 3.3 Narzędzia monitorowania (`nvidia-smi`)

Na serwerach headless pakiet `nvidia-utils` czasem nie jest dołączany automatycznie:

```bash
sudo apt install -y nvidia-utils-595-server
```

### 3.4 Alternatywa — sterownik desktop recommended

Jeśli wolisz iść ścieżką „recommended” z `ubuntu-drivers devices`:

```bash
sudo ubuntu-drivers install nvidia:595-open
sudo apt install -y nvidia-utils-595
```

Ta ścieżka też zadziała — ale dla serwera AI preferujemy wariant z sekcji 3.2.

### 3.5 Sprawdzenie zainstalowanych pakietów

```bash
dpkg -l | grep -i nvidia | grep -v linux-firmware
```

Oczekiwane m.in.: `nvidia-driver-595-server-open`, `nvidia-utils-595-server`.

---

## 4. Restart i pierwsze uruchomienie

Sterownik NVIDIA ładuje się do jądra dopiero po restarcie:

```bash
sudo reboot
```

Po restarcie zaloguj się ponownie przez SSH i wróć do sekcji 6 (Weryfikacja).

---

## 5. Konfiguracja serwerowa (opcjonalna)

Te kroki możesz wykonać po pierwszym udanym `nvidia-smi`.

### 5.1 Persistence mode

Zmniejsza opóźnienie przy pierwszym uruchomieniu workloadu GPU (kontenery startują szybciej):

```bash
# włącz persistence mode
sudo nvidia-smi -pm 1

# sprawdź
nvidia-smi | grep -i persistence
```

Aby włączać przy każdym bootcie, utwórz systemd service (opcjonalnie):

```bash
sudo tee /etc/systemd/system/nvidia-persistenced.service <<'EOF'
[Unit]
Description=NVIDIA Persistence Daemon
After=nvidia-persistenced.socket

[Service]
Type=forking
ExecStart=/usr/bin/nvidia-persistenced --user nvidia-persistenced
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now nvidia-persistenced 2>/dev/null || true
```

**Uwaga:** Na Ubuntu 26.04 daemon może już być zarządzany przez pakiet sterownika — jeśli `nvidia-persistenced` działa, nie twórz duplikatu.

### 5.2 Limit mocy GPU (opcjonalnie)

RTX 3090 Ti domyślnie pobiera dużo energii. Na serwerze domowym możesz ograniczyć TDP:

```bash
# sprawdź aktualny limit (450W max dla 3090 Ti)
nvidia-smi -q -d POWER | grep -E "Power Limit|Power Draw"

# przykład: limit 350W (wartość w mW) — dostosuj do swojego PSU
# sudo nvidia-smi -pl 350
```

Pomiń ten krok, jeśli zależy Ci na maksymalnej wydajności inference.

---

## 6. Weryfikacja

Wykonaj wszystkie punkty po restarcie.

### 6.1 `nvidia-smi`

```bash
nvidia-smi
```

Oczekiwane:
- GPU: **NVIDIA GeForce RTX 3090 Ti**
- Driver Version: **595.x**
- CUDA Version: wyświetlona (np. 12.x) — to wersja wspierana przez sterownik, nie osobna instalacja CUDA
- Brak błędów `NVIDIA-SMI has failed`

### 6.2 Wersja modułu jądra

```bash
cat /proc/driver/nvidia/version
```

### 6.3 Pełna lista GPU

```bash
nvidia-smi -L
```

Oczekiwane: jedna karta NVIDIA (GPU 0). iGPU AMD nie pojawia się w `nvidia-smi` — to prawidłowe.

### 6.4 Test obciążenia (krótki)

```bash
nvidia-smi dmon -s pucvmet -d 1 -c 3
```

Powinieneś zobaczyć odczyty temperatury, mocy i wykorzystania GPU.

### 6.5 Docker nadal działa

```bash
docker run --rm hello-world
```

Sterownik NVIDIA nie powinien zakłócić Dockera z rozdziału 01.

### Checklist

- [ ] `nvidia-smi` działa bez błędów
- [ ] Widoczna RTX 3090 Ti (24 GB VRAM)
- [ ] Driver Version 595.x
- [ ] `cat /proc/driver/nvidia/version` zwraca wersję
- [ ] Docker nadal działa (`hello-world` OK)
- [ ] (Opcjonalnie) persistence mode włączony

---

## 7. Troubleshooting

### 7.1 `NVIDIA-SMI has failed` po restarcie

**Przyczyna:** Moduł jądra nie załadowany lub konflikt z `nouveau`.

**Diagnostyka:**

```bash
lsmod | grep -E 'nvidia|nouveau'
dmesg | grep -i nvidia | tail -20
```

**Rozwiązanie:**

```bash
# nouveau powinien być wyłączony — jeśli załadowany:
cat /etc/modprobe.d/blacklist-nvidia-nouveau.conf 2>/dev/null

# przeinstaluj sterownik
sudo apt install --reinstall nvidia-driver-595-server-open
sudo reboot
```

### 7.2 DKMS — błąd kompilacji modułu

**Objaw:** Instalacja kończy się błędem DKMS.

**Rozwiązanie:**

```bash
# upewnij się, że masz nagłówki kernela
sudo apt install -y linux-headers-$(uname -r) build-essential dkms

# ponów instalację
sudo apt install --reinstall nvidia-driver-595-server-open
```

### 7.3 Secure Boot — moduł niepodpisany

**Objaw:** Po restarcie brak `nvidia` w `lsmod`, Secure Boot enabled.

Na tym serwerze Secure Boot jest wyłączony. Jeśli włączysz go później:

```bash
mokutil --sb-state
# wymagana rejestracja klucza MOK po instalacji sterownika
sudo reboot  # → menu MOK enrollment
```

### 7.4 `ubuntu-drivers install` — GUI nie działa

Na Ubuntu 26.04 zakładka „Additional Drivers” w GUI może być pusta — to znany problem. **Używaj wyłącznie CLI** (ten rozdział).

### 7.5 Po aktualizacji kernela — `nvidia-smi` przestaje działać

Po `apt upgrade` z nowym kernelem wymagany restart:

```bash
test -f /var/run/reboot-required && echo "Reboot required" || echo "OK"
sudo reboot
```

Ubuntu 26.04 na tym sprzęcie używa prebuilt modules (`linux-modules-nvidia-*`) — zwykle nie wymaga ręcznej rekompilacji DKMS.

### 7.6 Zła karta GPU używana przez aplikację

Jeśli w przyszłości pojawi się druga karta NVIDIA, wymuszaj:

```bash
export CUDA_VISIBLE_DEVICES=0
```

Dla RTX 3090 Ti jako jedynej karty NVIDIA w systemie domyślnie jest `GPU 0`.

---

## 8. Czego nie robimy w tym kroku

| Element | Rozdział |
|---------|----------|
| NVIDIA Container Toolkit (`nvidia-ctk`) | 03 |
| GPU w kontenerach Docker (`--gpus all`) | 03 |
| CUDA Toolkit na hoście | niepotrzebne — CUDA w kontenerach |
| vLLM | 04 |
| ComfyUI | 05 |
| Firewall | 06 |

---

## 9. Następny krok

Po przejściu checklisty z sekcji 6:

1. Zgłoś w rozmowie z Cursorem, że krok 02 jest gotowy (lub opisz problemy).
2. Przejdź do rozdziału [**03 — NVIDIA Container Toolkit**](03-nvidia-container-toolkit.md).

---

## Podsumowanie wykonanych zmian

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

- Zainstalowany sterownik `nvidia-driver-595-server-open` (lub `595-open`)
- Działające `nvidia-smi` z RTX 3090 Ti
- Narzędzia `nvidia-utils-595-server`
- Docker z rozdziału 01 nadal sprawny
- (Opcjonalnie) włączony persistence mode