tomasz-syn-grzegorza
359afb3a59
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>
475 lines
11 KiB
Markdown
475 lines
11 KiB
Markdown
# 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`
|