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,474 @@
+# 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`