ubuntu-bare-metal/manual-tutorial/01-system-update-and-docker.md

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

---

Spis treści

1. Weryfikacja punktu startowego
2. Aktualizacja systemu
3. Instalacja Docker CE
4. Konfiguracja post-install
5. Weryfikacja
6. Troubleshooting
7. Czego nie robimy w tym kroku
8. Następny krok

---

1. Weryfikacja punktu startowego

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

# 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

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:

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

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

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

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:

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

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)

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ź:

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

3.4 Instalacja pakietów Docker

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

sudo systemctl enable --now docker

Sprawdź status:

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:

sudo usermod -aG docker $USER

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

Opcja A — re-logowanie (zalecane):

# wyloguj się i zaloguj ponownie przez SSH
exit

Opcja B — tymczasowa aktywacja grupy (bez wylogowania):

newgrp docker

4.3 Konfiguracja rotacji logów

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

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

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

docker --version
docker compose version

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

5.2 Test hello-world

docker run --rm hello-world

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

Jeśli dostajesz permission denied — patrz Troubleshooting §6.1.

5.3 Status usługi

sudo systemctl is-active docker
sudo systemctl is-enabled docker

Oczekiwane: active i enabled.

5.4 Informacje o daemonie

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)

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:

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

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:

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:

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

# 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

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

---

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