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>
2026-07-05 12:02:04 +00:00
commit 359afb3a59
153 changed files with 18169 additions and 0 deletions
@@ -0,0 +1,102 @@
+# ADR-001: Host Agent + Control Plane UI
+
+**Status:** Zaakceptowany (research 2026-07-04)  
+**Kontekst:** Uniwersalny panel serwera (Server UI) + gpu-fan na gmktec-k11  
+**Pełna analiza:** [`SERVER-UI-ARCHITECTURE-RESEARCH.md`](SERVER-UI-ARCHITECTURE-RESEARCH.md)
+
+---
+
+## Kontekst i problem
+
+Na hoście działają:
+- **gpu-fan** (systemd, root, NVML) — port 8090, własny Web UI
+- **server-ui** (systemd) — port 8091, zarządzanie Docker compose
+- **Workloady AI** (Docker) — ComfyUI, LocalAI, vLLM
+
+Użytkownik chce:
+1. Jeden panel zamiast wielu portów (8090, 8091, …)
+2. UI serwerowe w Dockerze
+3. Operacje wymagające root (wentylatory GPU) nadal na hoście
+
+Pytanie: jak to pogodzić bez pakowania NVML do kontenera?
+
+---
+
+## Decyzja
+
+Przyjmujemy architekturę **dwuwarstwową**:
+
+1. **Host Agents** — procesy systemd jako root, API tylko na `127.0.0.1`, bez publicznego UI:
+   - `gpu-fan-daemon` (:18090) — NVML fan loop + REST API
+   - (przyszłość) `host-agent` — agregacja systemd, disk health
+
+2. **Control Plane UI** — Server UI (docelowo kontener Docker):
+   - Jeden dashboard, jeden `API_KEY` dla użytkownika
+   - Mount `/var/run/docker.sock` — orchestracja stacków
+   - HTTP proxy `/api/gpu-fan/*` → host agent
+
+**Strategia implementacji:** C z planu research (split gpu-fan → integracja UI → dockerize server-ui).
+
+---
+
+## Uzasadnienie
+
+| Alternatywa | Dlaczego odrzucona |
+|-------------|-------------------|
+| gpu-fan w Dockerze | NVML write na GeForce wymaga root na hoście; kruche, nieutrzymywane |
+| Status quo (dwa panele) | Rozproszony UX, dwa klucze |
+| Tylko Cockpit | Brak whitelist AI stacks, polityki GPU, custom NVML |
+| Monolit root z UI na 0.0.0.0 | Obecny gpu-fan — do refaktoru ze względów bezpieczeństwa |
+
+Wzorzec zgodny z **Portainer** (UI + docker.sock) i **Proxmox** (privileged daemons na hoście).
+
+---
+
+## Konsekwencje
+
+### Pozytywne
+- Jeden port publiczny dla panelu (:8091, potem opcjonalnie NPMPlus :443)
+- Daemon fan niezależny od UI — bezpieczeństwo termiczne przy padzie panelu
+- Możliwość rozszerzenia o `host-agent` bez kolejnych portów LAN
+
+### Negatywne / koszt
+- Refactor gpu-fan (rozdzielenie UI i API)
+- Dockerize server-ui (Dockerfile, mounty, testy `host.docker.internal`)
+- Dwa miejsca deploy: systemd (agenty) + compose (UI)
+
+### Neutralne
+- ComfyUI/LocalAI UI pozostają osobnymi aplikacjami (linki z dashboardu)
+- npmplus bez zmian (`network_mode: host`)
+
+---
+
+## Szczegóły techniczne (skrót)
+
+```
+Browser → server-ui:8091 (Docker)
+              ├─ docker.sock → compose stacks
+              └─ proxy → 127.0.0.1:18090 (gpu-fan-daemon, systemd root)
+```
+
+Env agenta:
+- `GPU_FAN_API_HOST=127.0.0.1`
+- `GPU_FAN_API_PORT=18090`
+
+Env server-ui:
+- `GPU_FAN_AGENT_URL=http://host.docker.internal:18090` (w Dockerze)
+
+---
+
+## Kiedy przejrzeć tę decyzję
+
+- Multi-node cluster (więcej niż jeden host) — wtedy centralny panel + agenty na każdym nodzie
+- Migracja na Cockpit/Kubernetes — osobna decyzja ADR
+- NVIDIA udostępni oficjalny fan API w kontenerach bez root — mało prawdopodobne na GeForce
+
+---
+
+## Powiązane dokumenty
+
+- [`SERVER-UI-ARCHITECTURE-RESEARCH.md`](SERVER-UI-ARCHITECTURE-RESEARCH.md)
+- [`../stacks/gpu-fan/coding-agent/DOCKER-VS-HOST-REPORT.md`](../stacks/gpu-fan/coding-agent/DOCKER-VS-HOST-REPORT.md)
+- [`DOCKER-UI-DEPLOYMENT.md`](DOCKER-UI-DEPLOYMENT.md)