ubuntu-bare-metal/README.md

# ubuntu-bare-metal

Repozytorium konfiguracji czystego Ubuntu na fizycznym serwerze (bare metal) pod hostowanie **vLLM**, **LocalAI**, **ComfyUI** i **Docker**.

Tutorial jest prowadzony krok po kroku — każdy rozdział to samodzielny etap z komendami, weryfikacją i sekcją troubleshooting.

## Sprzęt docelowy

| Parametr | Wartość |
|----------|---------|
| Urządzenie | GMKtec K11 |
| CPU | AMD Phoenix (Ryzen) |
| GPU (LLM / ComfyUI) | NVIDIA GeForce RTX 3090 Ti (24 GB VRAM) |
| iGPU | AMD HawkPoint1 (nieużywane do workloadów AI) |
| RAM | 29 GiB |
| Dysk systemowy | 128 GB NVMe (`/`) — tylko Ubuntu |
| Dysk danych | 1 TB (`/data`) — Docker, modele, aplikacje |
| System | Ubuntu 26.04 LTS (`resolute`) — instalacja minimized |

## Jak korzystać z tutoriala

1. Czytaj rozdziały w kolejności numeracji (`00`, `01`, `02`, …).
2. Wykonuj komendy na serwerze w podanej kolejności.
3. Po każdym rozdziale przejdź sekcję **Weryfikacja** — nie przechodź dalej, dopóki wszystkie punkty nie są zielone.
4. Zgłaszaj poprawki w rozmowie z Cursorem — tutorial będzie aktualizowany.

Instrukcje: **po polsku**. Komendy i nazwy pakietów: **po angielsku** (jak w systemie).

## Roadmapa rozdziałów

| # | Rozdział | Status |
|---|----------|--------|
| 00 | [Wymagania i konwencje](manual-tutorial/00-prerequisites.md) | Gotowy |
| 01 | [Aktualizacja systemu i Docker CE](manual-tutorial/01-system-update-and-docker.md) | Ukończony |
| 02 | [Sterowniki NVIDIA](manual-tutorial/02-nvidia-driver.md) | Ukończony |
| 03 | [NVIDIA Container Toolkit](manual-tutorial/03-nvidia-container-toolkit.md) | Ukończony |
| 03b | [Narzędzia bazowe — Ubuntu minimized](manual-tutorial/03b-system-tools.md) | **Wykonaj przed 04** |
| 04 | [Dysk 1 TB + vLLM stack](manual-tutorial/04-vllm-stack.md) | Ukończony / w toku |
| 05 | [LocalAI stack (UI + GGUF)](manual-tutorial/05-localai-stack.md) | Ukończony / w toku |
| 06 | [Sterowanie wentylatorami GPU](manual-tutorial/06-gpu-fan-control.md) | Gotowy |
| 07 | [ComfyUI stack (Docker)](manual-tutorial/07-comfyui-stack.md) | Gotowy (stack w repo) |
| 08 | [Server UI — panel sterowania](manual-tutorial/08-server-ui-install.md) | Gotowy |
| 09 | Firewall i hardening | Planowany |

```mermaid
flowchart LR
    step01["01: apt + Docker CE"]
    step02["02: NVIDIA driver"]
    step03["03: NVIDIA Container Toolkit"]
    step03b["03b: system tools"]
    step04["04: disk + vLLM"]
    step05["05: LocalAI stack"]
    step06["06: ComfyUI stack"]
    step07["07: firewall i hardening"]

    step01 --> step02 --> step03 --> step03b --> step04
    step04 --> step05
    step03 --> step06
    step05 --> step06
    step06 --> step07
```

Kolejność jest krytyczna: **Docker → sterownik GPU → nvidia-container-toolkit → workloady GPU w kontenerach**.

## Architektura dysków

| Dysk | Mount | Zawartość |
|------|-------|-----------|
| 128 GB NVMe | `/` | Ubuntu, `/etc`, `/home`, repo konfiguracyjne |
| 1 TB | `/data` | `/data/docker` (Docker), `/data/apps/*` (modele, LocalAI, ComfyUI) |

Szczegóły konfiguracji dysku 1 TB: rozdział [04 — vLLM stack](manual-tutorial/04-vllm-stack.md) (część A).

## Uwagi

- Do workloadów AI używamy wyłącznie **NVIDIA RTX 3090 Ti** (`CUDA_VISIBLE_DEVICES=0`), nie iGPU AMD.
- vLLM: brak domyślnego modelu — katalog w [`stacks/vllm/models.catalog.yaml`](stacks/vllm/models.catalog.yaml). Szczegóły: [`stacks/vllm/README.md`](stacks/vllm/README.md).
- LocalAI: UI + API na porcie **8070**, start bez modelu — [`stacks/localai/README.md`](stacks/localai/README.md).
- GPU Fan Control: web UI na porcie **8090** (SSH tunnel) — [`stacks/gpu-fan/README.md`](stacks/gpu-fan/README.md).
- Server UI: własny panel stacków na porcie **8091** — [`stacks/server-ui/README.md`](stacks/server-ui/README.md).
- Architektura panelu (gpu-fan + Docker UI): [`coding-agent/SERVER-UI-ARCHITECTURE-RESEARCH.md`](coding-agent/SERVER-UI-ARCHITECTURE-RESEARCH.md)

## Struktura repozytorium

```
ubuntu-bare-metal/
├── README.md
├── scripts/
│   └── setup-data-disk.sh       # migracja dysku 1 TB (rozdział 04A)
├── stacks/
│   ├── vllm/
│   │   ├── README.md
│   │   ├── models.catalog.yaml  # GGUF + vLLM AWQ, bez auto-download
│   │   ├── docker-compose.yml
│   │   ├── .env.example
│   │   ├── profiles/
│   │   │   ├── _template.env
│   │   │   └── qwen3.6-27b-awq-128k.env
│   │   └── scripts/
│   │       ├── list-models.sh
│   │       ├── download-model.sh
│   │       ├── switch-model.sh
│   │       └── start.sh
│   ├── llamacpp/
│   │   └── README.md              # placeholder pod GGUF (port 8001)
│   ├── localai/
│   │   ├── README.md
│   │   ├── docker-compose.yml
│   │   ├── .env.example
│   │   └── scripts/
│   │       ├── clone-upstream.sh
│   │       ├── pull.sh
│   │       └── start.sh
│   ├── comfyui/
│   │   ├── README.md
│   │   ├── docker-compose.yml
│   │   ├── .env.example
│   │   └── scripts/
│   │       ├── ensure-dirs.sh
│   │       ├── pull.sh
│   │       └── start.sh
│   ├── dockge/                    # DEPRECATED → server-ui
│   │   └── README.md
│   ├── server-ui/
│   │   ├── README.md
│   │   ├── app.py
│   │   ├── stacks.yaml
│   │   ├── server-ui.service
│   │   ├── static/index.html
│   │   └── scripts/
│   │       ├── install.sh
│   │       └── start.sh
│   └── gpu-fan/
│       ├── README.md
│       ├── app.py
│       ├── fan_controller.py
│       ├── curve.default.json
│       └── scripts/
│           ├── install.sh
│           └── start.sh
└── manual-tutorial/
    ├── 00-prerequisites.md
    ├── 01-system-update-and-docker.md
    ├── 02-nvidia-driver.md
    ├── 03-nvidia-container-toolkit.md
    ├── 03b-system-tools.md
    ├── 04-vllm-stack.md
    ├── 05-localai-stack.md
    ├── 06-gpu-fan-control.md
    ├── 07-comfyui-stack.md
    └── ... (kolejne rozdziały)
```