Files

T

tomasz-syn-grzegorza 359afb3a59 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

3.3 KiB

Raw Permalink Blame History

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

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:

Jeden panel zamiast wielu portów (8090, 8091, …)
UI serwerowe w Dockerze
Operacje wymagające root (wentylatory GPU) nadal na hoście

Pytanie: jak to pogodzić bez pakowania NVML do kontenera?

Decyzja

Przyjmujemy architekturę dwuwarstwową:

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

3.3 KiB Raw Permalink Blame History