Initial import: bare-metal stacks, Server UI, GPU fan, tutorials.

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>

coding-agent/HANDOFF.md

@@ -0,0 +1,104 @@
+# 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`