# Server UI — opcje instalacji (Control Plane)

**Data:** 2026-07-05  
**Host:** gmktec-k11  
**Kontekst:** Użytkownik nie widzi Server UI w `docker ps` — wyjaśnienie runtime + instalator z wyborem native/Docker.

**Powiązane:**
- [`stacks/server-ui/`](../stacks/server-ui/)
- [`manual-tutorial/08-server-ui-install.md`](../manual-tutorial/08-server-ui-install.md)
- [`ADR-001-host-agent-control-plane.md`](ADR-001-host-agent-control-plane.md)

---

## 1. Executive summary

- **Server UI** domyślnie działa jako **systemd** (`server-ui.service`, port 8091) — **nie** jako kontener Docker.
- **gpu-fan** działa wyłącznie jako **host agent** (systemd, port 18090 localhost) — Docker **nie jest obsługiwany** (NVML).
- Nowy skrypt **`install-control-plane.sh`** instaluje oba komponenty z menu: gpu-fan native + Server UI native **lub** Docker.
- Tutorial dla użytkownika: [`08-server-ui-install.md`](../manual-tutorial/08-server-ui-install.md).

---

## 2. Architektura

```mermaid
flowchart TB
    subgraph dockerStacks [Docker workloads]
        comfyui[comfyui :8188]
        localai[localai :8070]
        npmplus[npmplus :81]
    end
    subgraph hostNative [Host systemd]
        gpufan[gpu-fan agent :18090]
    end
    subgraph serverUINative [Server UI native]
        suiNative[server-ui :8091]
    end
    subgraph serverUIDocker [Server UI docker optional]
        suiDocker[container server-ui :8091]
    end
    browser[Browser] --> suiNative
    browser -.-> suiDocker
    suiNative --> dockerStacks
    suiDocker --> dockerStacks
    suiNative --> gpufan
    suiDocker --> gpufan
    gpufan --> gpu[RTX 3090 Ti]
```

---

## 3. Instalator

**Ścieżka:** `stacks/server-ui/scripts/install-control-plane.sh`

| Flaga | Wartości | Domyślnie (-y) |
|-------|----------|----------------|
| `--gpu-fan` | yes, no, skip | yes |
| `--server-ui` | native, docker, skip | native |

**Przykłady:**

```bash
cd ~/cursor/ubuntu-bare-metal/stacks/server-ui
sudo ./scripts/install-control-plane.sh              # interaktywne menu
sudo ./scripts/install-control-plane.sh -y             # gpu-fan + server-ui native
sudo ./scripts/install-control-plane.sh --gpu-fan=yes --server-ui=docker
```

**Skrypty pomocnicze:**

| Skrypt | Rola |
|--------|------|
| `install-control-plane.sh` | Menu: gpu-fan + server-ui |
| `install.sh` | Tylko Server UI native |
| `install-docker.sh` | Tylko Server UI Docker |

Przy przełączaniu native ↔ Docker instalator wyłącza drugi tryb (systemd disable lub `compose down`).

---

## 4. Klucze API

Jeden plik dla gpu-fan + Server UI:

| Środowisko | Plik | Zmienna |
|------------|------|---------|
| Produkcja (systemd) | `/opt/control-plane/.env` | `API_KEY` |
| Dev / Docker | `stacks/control-plane/.env` | `API_KEY` |

`API_KEY` służy do auth panelu (`X-API-Key`) **i** proxy `/api/gpu-fan/*` do agenta.

```bash
grep ^API_KEY= /opt/control-plane/.env
```

Szczegóły: [`CONTROL-PLANE-ENV.md`](CONTROL-PLANE-ENV.md)

---

## 5. Server UI w Dockerze

| Plik | Opis |
|------|------|
| `Dockerfile` | Python 3.12 + docker CLI + compose plugin |
| `docker-compose.yml` | profil `server-ui`, mount `docker.sock` + repo `/repo` |
| `install-docker.sh` | build, up, generacja `.env` |

**GPU fan z kontenera:** `GPU_FAN_AGENT_URL=http://host.docker.internal:18090` + `extra_hosts: host-gateway`.

**Wymagania:** `REPO_ROOT` w `.env` wskazuje na katalog z `stacks/` (mount read-only do `/repo`).

---

## 6. Weryfikacja

```bash
# Native
systemctl is-active server-ui gpu-fan
curl -s http://127.0.0.1:8091/api/health

# Docker
docker compose --profile server-ui ps
curl -s http://127.0.0.1:8091/api/stacks
```

---

## 7. Checklist wdrożenia

- [x] `Dockerfile`, `docker-compose.yml`, `install-docker.sh`
- [x] `install-control-plane.sh`
- [x] `manual-tutorial/08-server-ui-install.md`
- [x] README server-ui + główny README (rozdział 08)
- [ ] Na produkcji: `sudo ./scripts/install-control-plane.sh` lub `install.sh` / `install-docker.sh`
- [ ] Test GPU Fan proxy po instalacji Docker

---

## 8. Dlaczego gpu-fan bez Docker

Patrz [`stacks/gpu-fan/coding-agent/DOCKER-VS-HOST-REPORT.md`](../stacks/gpu-fan/coding-agent/DOCKER-VS-HOST-REPORT.md) i ADR-001. Instalator wyświetla komunikat i oferuje tylko native.