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