# Handoff — sesja ubuntu-bare-metal

Dokument dla agenta kontynuującego pracę. Ostatni znany stan po sesji konfiguracji serwera LLM na GMKtec K11.

## Kontekst projektu

| Element | Wartość |
|---------|---------|
| Repo | `/home/tomasz-syn-grzegorza/cursor/ubuntu-bare-metal` |
| Urządzenie | GMKtec K11 |
| OS | Ubuntu 26.04 LTS minimized (`resolute`) |
| GPU | NVIDIA GeForce RTX 3090 Ti, 24 GB VRAM (`CUDA_VISIBLE_DEVICES=0`) |
| RAM | ~29 GiB |
| Dysk systemowy | `nvme1n1` 128 GB → `/` |
| Dysk danych | `nvme0n1` 1 TB → `/data` |
| Docker data-root | `/data/docker` |
| Użytkownik | `tomasz-syn-grzegorza` (sudo) |

**Workflow:** tutorial krok po kroku w [`manual-tutorial/`](../manual-tutorial/). Użytkownik czyta markdown i wykonuje komendy ręcznie. Agent nie może wpisać hasła `sudo` interaktywnie — skrypty wymagające sudo użytkownik uruchamia w swoim terminalu SSH.

## Ukończone (infrastruktura + repo)

| Rozdział / obszar | Status |
|-------------------|--------|
| 01 — Docker CE ~29.x | Ukończony przez użytkownika |
| 02 — NVIDIA driver 595 open | Ukończony |
| 03 — NVIDIA Container Toolkit 1.19 | Ukończony |
| 03b — narzędzia minimized | Dokumentacja gotowa |
| 04A — dysk 1 TB, fstab, migracja Docker | Ukończony (`scripts/setup-data-disk.sh`) |
| 04B — stack vLLM | Repo gotowe; obraz Docker pobrany; **kontener nie uruchomiony** (brak modelu) |
| Katalog modeli vLLM | `stacks/vllm/models.catalog.yaml` + skrypty list/download/switch |
| Placeholder llama.cpp | `stacks/llamacpp/README.md` |
| 05 — stack LocalAI | Repo gotowe; **kontener uruchomiony przez użytkownika** |
| LocalAI API key | Użytkownik dodał `LOCALAI_API_KEY` do `stacks/localai/.env` — **wartość nie dokumentowana tutaj** |

## Stan runtime (faktyczny na serwerze)

| Serwis | Stan |
|--------|------|
| vLLM | Obraz `vllm/vllm-openai:latest` na dysku; kontener **nie działa** (`VLLM_MODEL` puste w `.env`) |
| LocalAI | Kontener `localai` **running**; obraz `localai/localai:v4.4.3-gpu-nvidia-cuda-13` |
| Model LocalAI | Użytkownik **w trakcie pobierania** modelu (prawdopodobnie przez UI / galerię) |
| API key | Ustawiony w `.env` — **wymaga** przekazania do kontenera w `docker-compose.yml` + restart (patrz BACKLOG P0) |

## Porty

| Serwis | Port w dokumentacji | Port faktyczny (`.env` użytkownika) |
|--------|---------------------|-------------------------------------|
| vLLM API | 8000 | 8000 (nieaktywny) |
| LocalAI UI + API | 8080 | **8070** |
| llama.cpp (plan) | 8001 | nie wdrożony |

Wewnątrz kontenera LocalAI zawsze nasłuchuje na **8080**; mapowanie hosta ustawia `LOCALAI_PORT` w `.env`.

## Decyzje techniczne (nie zmieniać bez uzgodnienia)

1. **GGUF** z lmstudio-community **nie działa** w standardowym `vllm/vllm-openai` — użycie przez LocalAI (llama.cpp backend) lub przyszły host llama.cpp.
2. **vLLM interim** dla Q4-odpowiednika: AWQ `Qwen/Qwen3.6-27B-Instruct-AWQ`, profil `qwen3.6-27b-awq-128k`, kontekst 128K (`MAX_MODEL_LEN=131072`), KV `fp8`.
3. **LocalAI:** oficjalny obraz Docker (nie build ze źródeł); bez `command: phi-2` (brak auto-pobierania modelu przy starcie).
4. **Jeden duży model w VRAM** naraz na 24 GB — nie uruchamiać vLLM + LocalAI z dużymi modelami równolegle.
5. **Modele docelowe (katalog):** Qwen3.6-27B Q4_K_M GGUF, Gemma 4 12B Q4_0 GGUF (lmstudio-community).
6. **Brak domyślnego modelu** przy instalacji stacków — pobieranie on-demand.

## Co zrobiono w repo (implementacja agenta)

### vLLM (`stacks/vllm/`)

- `models.catalog.yaml` — GGUF (llamacpp) + AWQ (vllm)
- Elastyczny `docker-compose.yml` + `vllm-entrypoint.sh` (`QUANTIZATION`, `VLLM_EXTRA_ARGS`)
- Skrypty: `list-models.sh`, `download-model.sh`, `switch-model.sh`, `start.sh`
- Profile: `qwen3.6-27b-awq-128k.env`, `_template.env`
- Tutorial część B w `manual-tutorial/04-vllm-stack.md`

### LocalAI (`stacks/localai/`)

- `docker-compose.yml`, `.env.example`, skrypty `pull.sh`, `start.sh`, `clone-upstream.sh`
- Bind mounty na `/data/apps/localai/{models,backends,configuration,images,data}`
- Tutorial `manual-tutorial/05-localai-stack.md`
- Roadmapa root README: 05 LocalAI, 06 ComfyUI, 07 firewall

### Inne

- `scripts/setup-data-disk.sh` — rozszerzony o katalogi `gguf/` i `localai/`

## Ostatnia rozmowa (advisory — nie wdrożone w repo)

Użytkownik pytał o:

1. **Wystawienie endpointu przez domenę** — reverse proxy (Caddy/nginx) + DNS + HTTPS; LocalAI za proxy na `127.0.0.1:PORT`.
2. **API token** — opcja A: `LOCALAI_API_KEY` (legacy, pełny admin); opcja B: `LOCALAI_AUTH=true` + `LOCALAI_BASE_URL` (konta użytkowników).

Brak w repo: `Caddyfile`, rozdział proxy/TLS, wpis `LOCALAI_API_KEY` w `docker-compose.yml`.

## Następny agent — zacznij od

1. Przeczytaj [BACKLOG.md](BACKLOG.md) — sekcja **P0**.
2. Napraw przekazanie `LOCALAI_API_KEY` do kontenera i zweryfikuj auth po restarcie.
3. Uzgodnij z użytkownikiem port **8070** vs **8080** w dokumentacji.
4. Po zakończeniu pobierania modelu — test chat w UI i `curl /v1/chat/completions`.

## Transkrypt sesji

Pełna historia rozmowy (Cursor):  
`/home/tomasz-syn-grzegorza/.cursor/projects/home-tomasz-syn-grzegorza/agent-transcripts/f1d1befe-e1e0-44e8-8a40-1f175e6df09c/f1d1befe-e1e0-44e8-8a40-1f175e6df09c.jsonl`