# 01 — Aktualizacja systemu i instalacja Docker CE

> **Cel rozdziału:** zaktualizować świeży Ubuntu 26.04 LTS i zainstalować Docker Engine z oficjalnego repozytorium Docker Inc. (nie `docker.io` z Ubuntu).

**Szacowany czas:** 10–20 minut (zależy od liczby pakietów do aktualizacji)

**Wymagania:** rozdział [00 — Wymagania i konwencje](00-prerequisites.md)

---

## Spis treści

1. [Weryfikacja punktu startowego](#1-weryfikacja-punktu-startowego)
2. [Aktualizacja systemu](#2-aktualizacja-systemu)
3. [Instalacja Docker CE](#3-instalacja-docker-ce)
4. [Konfiguracja post-install](#4-konfiguracja-post-install)
5. [Weryfikacja](#5-weryfikacja)
6. [Troubleshooting](#6-troubleshooting)
7. [Czego nie robimy w tym kroku](#7-czego-nie-robimy-w-tym-kroku)
8. [Następny krok](#8-następny-krok)

---

## 1. Weryfikacja punktu startowego

Przed jakimikolwiek zmianami potwierdź stan systemu. Te komendy **nic nie modyfikują**.

```bash
# wersja Ubuntu — oczekiwane: 26.04, codename: resolute
lsb_release -a

# kernel
uname -r

# wolne miejsce na dysku głównym (minimum ~5 GB na upgrade + Docker)
df -h /

# uprawnienia sudo
groups | grep -q sudo && echo "sudo: OK" || echo "sudo: BRAK — wymagane!"

# Docker nie powinien być jeszcze zainstalowany
docker --version 2>/dev/null || echo "Docker: not installed (expected)"

# GPU widoczne w PCI (sterownik jeszcze niepotrzebny)
lspci | grep -i "nvidia"
```

**Oczekiwany wynik:**

- Ubuntu 26.04 LTS (`resolute`)
- Użytkownik w grupie `sudo`
- Docker niezainstalowany
- NVIDIA RTX 3090 Ti widoczna w `lspci`

**Uwaga:** `nvidia-smi` nie działa na tym etapie — to normalne. Sterowniki instalujemy w rozdziale 02.

---

## 2. Aktualizacja systemu

### 2.1 Aktualizacja list pakietów i upgrade

```bash
sudo apt update
sudo apt upgrade -y
```

Pierwszy pełny upgrade na świeżej instalacji może pobrać setki pakietów — poczekaj na zakończenie.

### 2.2 Instalacja pakietów bazowych

Te pakiety są potrzebne do dodania repozytorium Docker i dalszej konfiguracji serwera:

```bash
sudo apt install -y \
  ca-certificates \
  curl \
  gnupg \
  lsb-release \
  apt-transport-https \
  software-properties-common
```

| Pakiet | Po co |
|--------|-------|
| `ca-certificates` | Weryfikacja certyfikatów HTTPS (repo Docker) |
| `curl` | Pobieranie kluczy GPG i plików z internetu |
| `gnupg` | Weryfikacja podpisów pakietów |
| `lsb-release` | Odczyt wersji Ubuntu (codename `resolute`) |
| `apt-transport-https` | Obsługa repozytoriów HTTPS przez apt |
| `software-properties-common` | Narzędzia do zarządzania repozytoriami |

### 2.3 Sprawdzenie, czy wymagany jest restart

```bash
# jeśli plik istnieje — kernel lub libc wymagają restartu
test -f /var/run/reboot-required && cat /var/run/reboot-required || echo "Restart not required"
```

Jeśli restart jest wymagany:

```bash
sudo reboot
```

Po restarcie zaloguj się ponownie i wróć do tego rozdziału od sekcji 3.

**Uwaga:** Na tym systemie `unattended-upgrades` jest domyślnie aktywny — to dobrze dla bezpieczeństwa. Pierwszy pełny upgrade wykonujemy jednak ręcznie, żeby mieć kontrolę nad procesem.

---

## 3. Instalacja Docker CE

Instalujemy Docker z **oficjalnego repozytorium Docker Inc.**, nie z pakietu `docker.io` dostępnego w repozytoriach Ubuntu. Oficjalne repo daje:

- najnowsze wersje Engine,
- plugin `docker compose` (v2),
- plugin `docker-buildx`,
- bezpośrednią ścieżkę aktualizacji (`apt upgrade`).

Dokumentacja: [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/)

### 3.1 Usunięcie konfliktowych pakietów

Jeśli wcześniej nic nie instalowałeś, ten krok nic nie usunie — ale warto go wykonać dla czystości:

```bash
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do
  sudo apt remove -y $pkg 2>/dev/null
done
```

### 3.2 Dodanie oficjalnego klucza GPG Docker

```bash
sudo install -m 0755 -d /etc/apt/keyrings

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc

sudo chmod a+r /etc/apt/keyrings/docker.asc
```

### 3.3 Dodanie repozytorium Docker (format DEB822)

```bash
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
```

Na Ubuntu 26.04 LTS pole `Suites` powinno wskazywać na `resolute`. Sprawdź:

```bash
grep Suites /etc/apt/sources.list.d/docker.sources
# oczekiwane: Suites: resolute
```

### 3.4 Instalacja pakietów Docker

```bash
sudo apt update

sudo apt install -y \
  docker-ce \
  docker-ce-cli \
  containerd.io \
  docker-buildx-plugin \
  docker-compose-plugin
```

| Pakiet | Rola |
|--------|------|
| `docker-ce` | Docker Engine (daemon `dockerd`) |
| `docker-ce-cli` | CLI (`docker` command) |
| `containerd.io` | Niskopoziomowy runtime kontenerów |
| `docker-buildx-plugin` | Nowoczesny builder obrazów (BuildKit) |
| `docker-compose-plugin` | `docker compose` — zarządzanie wieloma kontenerami |

---

## 4. Konfiguracja post-install

### 4.1 Włączenie i uruchomienie usługi Docker

```bash
sudo systemctl enable --now docker
```

Sprawdź status:

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

Oczekiwane: `Active: active (running)`

### 4.2 Dodanie użytkownika do grupy `docker`

Bez tego każda komenda `docker` wymaga `sudo`:

```bash
sudo usermod -aG docker $USER
```

**Ważne:** Grupa `docker` zostanie aktywna dopiero po ponownym zalogowaniu. Masz dwie opcje:

**Opcja A — re-logowanie (zalecane):**

```bash
# wyloguj się i zaloguj ponownie przez SSH
exit
```

**Opcja B — tymczasowa aktywacja grupy (bez wylogowania):**

```bash
newgrp docker
```

### 4.3 Konfiguracja rotacji logów

Kontenery vLLM i ComfyUI generują dużo logów. Bez rotacji dysk szybko się zapełni.

```bash
sudo mkdir -p /etc/docker

sudo tee /etc/docker/daemon.json <<'EOF'
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "50m",
    "max-file": "3"
  }
}
EOF

sudo systemctl restart docker
```

To ogranicza logi każdego kontenera do 3 plików po 50 MB (max ~150 MB na kontener).

### 4.4 Opcjonalnie: live-restore

Jeśli chcesz, żeby kontenery działały podczas restartu daemona Docker (np. przy aktualizacji):

```bash
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "50m",
    "max-file": "3"
  },
  "live-restore": true
}
EOF

sudo systemctl restart docker
```

**Kompromis:** `live-restore` utrudnia debugowanie i może maskować problemy z daemonem. Na serwerze produkcyjnym zwykle warto — na etapie konfiguracji możesz pominąć.

---

## 5. Weryfikacja

Wykonaj wszystkie punkty. Nie przechodź do rozdziału 02, dopóki każdy nie przejdzie.

### 5.1 Wersje Docker i Compose

```bash
docker --version
docker compose version
```

Oczekiwane: Docker version 29.x (lub nowszy), Compose v2.x jako plugin.

### 5.2 Test hello-world

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

Oczekiwane: komunikat `Hello from Docker!` i `status code: 0`.

Jeśli dostajesz `permission denied` — patrz [Troubleshooting §6.1](#61-permission-denied-na-varrundockersock).

### 5.3 Status usługi

```bash
sudo systemctl is-active docker
sudo systemctl is-enabled docker
```

Oczekiwane: `active` i `enabled`.

### 5.4 Informacje o daemonie

```bash
docker info 2>/dev/null | grep -E 'Server Version|Storage Driver|Cgroup Driver|Logging Driver'
```

Oczekiwane m.in.:
- `Storage Driver: overlay2`
- `Logging Driver: json-file`

### 5.5 Test bez sudo (po re-logowaniu / newgrp)

```bash
docker ps
```

Oczekiwane: pusta lista kontenerów, **bez** błędu uprawnień.

### Checklist

- [ ] `docker --version` działa
- [ ] `docker compose version` działa
- [ ] `docker run --rm hello-world` zakończone sukcesem
- [ ] `systemctl status docker` → active (running)
- [ ] `docker ps` działa bez `sudo`
- [ ] `/etc/docker/daemon.json` istnieje z rotacją logów

---

## 6. Troubleshooting

### 6.1 Permission denied na `/var/run/docker.sock`

```
permission denied while trying to connect to the Docker daemon socket
```

**Przyczyna:** Użytkownik nie jest w grupie `docker` lub nie zalogował się ponownie po `usermod`.

**Rozwiązanie:**

```bash
# sprawdź grupy
groups

# jeśli brak "docker":
sudo usermod -aG docker $USER
newgrp docker   # lub wyloguj się i zaloguj ponownie
```

### 6.2 `docker-ce has no installation candidate`

**Przyczyna:** Błędny codename w `/etc/apt/sources.list.d/docker.sources`.

**Rozwiązanie:**

```bash
grep Suites /etc/apt/sources.list.d/docker.sources
# musi być: Suites: resolute

# jeśli inny — usuń i dodaj repo ponownie (sekcja 3.3)
sudo rm /etc/apt/sources.list.d/docker.sources
# ... powtórz kroki 3.2 i 3.3
```

### 6.3 Konflikt z `docker.io`

**Objaw:** apt instaluje `docker.io` zamiast `docker-ce`, lub oba się gryzą.

**Rozwiązanie:**

```bash
sudo apt remove -y docker.io docker-doc docker-compose docker-compose-v2
sudo apt autoremove -y
# powtórz sekcję 3.4
```

### 6.4 Błąd pobierania klucza GPG

```
curl: (6) Could not resolve host: download.docker.com
```

**Przyczyna:** Brak internetu lub problem DNS.

**Rozwiązanie:**

```bash
# test połączenia
ping -c 3 download.docker.com
ping -c 3 8.8.8.8

# sprawdź DNS
cat /etc/resolv.conf
```

### 6.5 Daemon nie startuje po `daemon.json`

**Objaw:** `systemctl status docker` → failed.

**Przyczyna:** Błędny JSON w `/etc/docker/daemon.json`.

**Rozwiązanie:**

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

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

sudo systemctl restart docker
```

### 6.6 `hello-world` — image pull failed

```bash
# test dostępu do Docker Hub
docker pull hello-world

# sprawdź logi daemona
sudo journalctl -u docker --no-pager -n 50
```

---

## 7. Czego nie robimy w tym kroku

Świadomie **pomijamy** — pojawią się w kolejnych rozdziałach:

| Element | Rozdział |
|---------|----------|
| Sterowniki NVIDIA (`nvidia-driver-*`) | 02 |
| `nvidia-smi`, CUDA toolkit | 02 |
| NVIDIA Container Toolkit (`nvidia-ctk`) | 03 |
| GPU w kontenerach (`--gpus all`) | 03 |
| vLLM | 04 |
| ComfyUI | 05 |
| UFW / firewall / fail2ban | 06 |
| Katalog `/data` na modele | później |

Docker zainstalowany w tym rozdziale **nie ma dostępu do GPU** — to zamierzone. Najpierw fundament, potem warstwy.

---

## 8. Następny krok

Po przejściu checklisty z sekcji 5:

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

---

## Podsumowanie wykonanych zmian

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

- Zaktualizowany system Ubuntu 26.04 LTS
- Zainstalowany Docker CE z oficjalnego repo
- Pluginy `docker compose` i `docker-buildx`
- Użytkownik w grupie `docker`
- Skonfigurowana rotacja logów w `/etc/docker/daemon.json`
- Działający test `hello-world`