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](01-system-update-and-docker.md)

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

---

## Spis treści

1. [Filozofia: host vs Docker](#1-filozofia-host-vs-docker)
2. [Co już masz po krokach 01–03](#2-co-już-masz-po-krokach-0103)
3. [Instalacja pakietów bazowych](#3-instalacja-pakietów-bazowych)
4. [Python na hoście — co i czego nie](#4-python-na-hoście--co-i-czego-nie)
5. [Git i repozytorium konfiguracyjne](#5-git-i-repozytorium-konfiguracyjne)
6. [Weryfikacja](#6-weryfikacja)
7. [Opcjonalne narzędzia](#7-opcjonalne-narzędzia)
8. [Czego świadomie NIE instalujemy na hoście](#8-czego-świadomie-nie-instalujemy-na-hoście)
9. [Następny krok](#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 |

```mermaid
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:

```bash
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:

```bash
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:

```bash
# 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

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

```bash
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`:

```bash
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`:

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

### 5.2 Podstawowa konfiguracja git (opcjonalnie)

```bash
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

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

```bash
# 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](04-vllm-stack.md)

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