ubuntu-bare-metal/manual-tutorial/03b-system-tools.md

03b — Narzędzia bazowe (Ubuntu minimized)

Cel rozdziału: doinstalować minimalny zestaw narzędzi systemowych na Ubuntu minimized — tylko to, co potrzebne na hoście. vLLM, ComfyUI i CUDA działają w Dockerze, nie na systemie.

Szacowany czas: 5 minut

Wymagania: ukończony rozdział 01 — Docker CE

Kiedy wykonać: przed rozdziałem 04 — dysk + vLLM. Można zrobić teraz (kroki 01–03 już ukończone).

---

Spis treści

1. Filozofia: host vs Docker
2. Co już masz po krokach 01–03
3. Instalacja pakietów bazowych
4. Python na hoście — co i czego nie
5. Git i repozytorium konfiguracyjne
6. Weryfikacja
7. Opcjonalne narzędzia
8. Czego świadomie NIE instalujemy na hoście
9. Następny krok

---

1. Filozofia: host vs Docker

Ubuntu minimized to świadomie odchudzona instalacja — bez edytorów, bez wielu narzędzi deweloperskich, bez GUI. Na serwerze AI trzymamy się zasady:

Warstwa	Co tam żyje	Przykłady
Host (128 GB /)	System, Docker, sterowniki, konfiguracja	git, python3, nano, rsync, parted
Docker (/data/docker)	Obrazy i kontenery	vLLM, ComfyUI, CUDA runtime
Dane (/data/apps)	Modele, checkpointy, cache	Hugging Face, ComfyUI models

flowchart TB
    host["Host Ubuntu minimized"]
    docker["Docker Engine"]
    vllm["Kontener vLLM — Python + PyTorch + CUDA"]
    comfy["Kontener ComfyUI — Python + torch"]

    host --> docker
    docker --> vllm
    docker --> comfy

Nie instalujemy PyTorch, CUDA Toolkit ani vLLM na hoście — wszystko to jest w kontenerach. Host dostaje tylko narzędzia administracyjne.

---

2. Co już masz po krokach 01–03

Sprawdź aktualny stan:

for cmd in git python3 curl wget docker nvidia-smi; do
  printf "%-12s " "$cmd"
  command -v $cmd 2>/dev/null || echo "BRAK"
done
python3 --version
git --version

Na typowym stanie po rozdziałach 01–03:

Narzędzie	Status	Skąd
git	zazwyczaj jest	zależność systemowa / automatyczna
python3	jest (minimalny)	preinstalowany na Ubuntu
curl, wget	są	rozdział 01
docker	jest	rozdział 01
nvidia-smi	jest	rozdział 02
nano, vim	brak	minimized
rsync	brak	potrzebny do migracji Docker → /data
parted	brak	potrzebny do partycjonowania dysku 1 TB
jq	brak	wygodne testy API vLLM
pip3	brak	celowo — patrz sekcja 4

---

3. Instalacja pakietów bazowych

Jedna komenda — zestaw dla administracji serwerem i kolejnych rozdziałów tutoriala:

sudo apt update

sudo apt install -y \
  git \
  python3 \
  python3-venv \
  nano \
  vim \
  jq \
  rsync \
  parted \
  e2fsprogs \
  util-linux \
  htop \
  tmux \
  tree \
  unzip \
  zip \
  pciutils \
  usbutils \
  net-tools \
  smartmontools

Po co który pakiet

Pakiet	Po co na tym serwerze
git	Wersjonowanie ubuntu-bare-metal, klonowanie configów
python3	python3 -m json.tool, skrypty admin (stdlib)
python3-venv	Izolowane środowiska Python — jeśli kiedyś własny skrypt
nano / vim	Edycja .env, fstab, daemon.json
jq	Parsowanie JSON z API vLLM (curl ... | jq)
rsync	Migracja /var/lib/docker → /data/docker (rozdział 04)
parted	Partycjonowanie dysku 1 TB (rozdział 04)
e2fsprogs	mkfs.ext4, fsck — formatowanie /data
util-linux	lsblk, blkid, mount — diagnostyka dysków
htop	Monitorowanie CPU/RAM
tmux	Sesje SSH — proces nie ginie po rozłączeniu
tree	Podgląd struktury /data
pciutils	lspci — diagnostyka GPU
smartmontools	smartctl — zdrowie dysków (opcjonalnie, ale przydatne)

---

4. Python na hoście — co i czego nie

Co mamy

Ubuntu 26.04 minimized dostarcza Python 3.14 (minimalny) — wystarczy do:

# formatowanie JSON z API
curl -s http://localhost:8000/v1/models | python3 -m json.tool

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

Czego NIE robimy na hoście

# NIE instaluj tego na hoście:
# pip install torch vllm transformers
# apt install nvidia-cuda-toolkit

Ubuntu 26.04 blokuje też pip install do systemowego Pythona (PEP 668 — „externally managed environment”). To dobre — chroni system przed bałaganem.

Jeśli kiedyś potrzebujesz własnego skryptu Python na hoście:

python3 -m venv ~/venv
source ~/venv/bin/activate
pip install requests   # tylko w venv, nie globalnie
deactivate

Dla vLLM i ComfyUI — nie potrzebujesz venv na hoście.

---

5. Git i repozytorium konfiguracyjne

5.1 Inicjalizacja repo (jeśli jeszcze nie zrobione)

Repozytorium konfiguracyjne trzymamy na dysku systemowym (lekki tekst), nie na /data:

cd /home/tomasz-syn-grzegorza/cursor/ubuntu-bare-metal

git init
git add README.md manual-tutorial/ stacks/
git status

Nie commituj plików .env z tokenami — tylko .env.example.

Opcjonalnie .gitignore:

cat > .gitignore <<'EOF'
.env
*.log
__pycache__/
.venv/
EOF

5.2 Podstawowa konfiguracja git (opcjonalnie)

git config --global user.name "Twoje Imię"
git config --global user.email "twoj@email.com"

Bez tego git commit zapyta o autora przy pierwszym commicie.

---

6. Weryfikacja

# pakiety kluczowe
for cmd in git python3 nano vim jq rsync parted lsblk blkid htop tmux; do
  printf "%-12s " "$cmd"
  command -v $cmd 2>/dev/null || echo "BRAK"
done

# wersje
python3 --version
git --version
jq --version

# test jq
echo '{"status":"ok"}' | jq .

# test rsync
rsync --version | head -1

# test parted
parted --version | head -1

Checklist

• nano lub vim działa
• jq formatuje JSON
• rsync dostępny (rozdział 04 — migracja Docker)
• parted i lsblk dostępne (rozdział 04 — dysk 1 TB)
• git status w katalogu ubuntu-bare-metal działa

---

7. Opcjonalne narzędzia

Instaluj tylko jeśli potrzebujesz:

# kompilacja czegoś ze źródeł (zwykle niepotrzebne na tym serwerze)
# sudo apt install -y build-essential

# monitorowanie GPU w czasie rzeczywistym (wygodniejsze niż watch nvidia-smi)
# sudo apt install -y nvtop

# sieć — ss jest nowocześniejszy niż netstat
ss -tlnp

# synchronizacja czasu (zwykle już działa)
timedatectl status

---

8. Czego świadomie NIE instalujemy na hoście

Pakiet / narzędzie	Dlaczego nie
nvidia-cuda-toolkit	CUDA jest w kontenerach Docker
python3-pip (globalnie)	PEP 668; używaj venv lub jq
torch, vllm, transformers (pip)	Działają w kontenerze vLLM
nodejs, npm	ComfyUI w Dockerze
docker.io (Ubuntu)	Mamy docker-ce z rozdziału 01
GUI / desktop	Serwer headless
snap pakiety	Niepotrzebna złożoność na serwerze

---

9. Następny krok

→ 04 — Dysk danych 1 TB + vLLM stack

Kolejność:

1. Ten rozdział (03b) — narzędzia bazowe
2. Rozdział 04 część A — dysk 1 TB + migracja Docker
3. Rozdział 04 część B — uruchomienie vLLM