# 08 — Server UI i panel sterowania (Control Plane)

> **Cel rozdziału:** zainstalować panel Server UI do zarządzania stackami Docker (LocalAI, ComfyUI, vLLM, NPMPlus) oraz zakładkę GPU Fan — i wiedzieć, gdzie są klucze API.

**Szacowany czas:** 10–15 minut

**Wymagania:** rozdział [01 — Docker](01-system-update-and-docker.md); opcjonalnie [06 — gpu-fan](06-gpu-fan-control.md) dla zakładki wentylatorów

---

## Spis treści

1. [Co to jest Server UI](#1-co-to-jest-server-ui)
2. [Dlaczego nie ma go w docker ps](#2-dlaczego-nie-ma-go-w-docker-ps)
3. [Instalacja jednym skryptem](#3-instalacja-jednym-skryptem)
4. [Gdzie są klucze API](#4-gdzie-są-klucze-api)
5. [Jak uruchomić i otworzyć panel](#5-jak-uruchomić-i-otworzyć-panel)
6. [Tryb Docker (opcjonalnie)](#6-tryb-docker-opcjonalnie)
7. [Troubleshooting](#7-troubleshooting)
8. [Następny krok](#8-następny-krok)

---

## 1. Co to jest Server UI

**Server UI** to jeden panel w przeglądarce (port **8091**), w którym możesz:

- włączać i wyłączać stacki Docker (Start / Stop / Restart),
- przeglądać logi kontenerów,
- otwierać linki do LocalAI, ComfyUI, vLLM, NPMPlus,
- zmieniać porty usług (zapis do `.env` stacku),
- sterować wentylatorami GPU (zakładka **GPU Fan**).

Zastępuje Portainer i Dockge.

---

## 2. Dlaczego nie ma go w `docker ps`

Komenda `docker ps` pokazuje **tylko kontenery Docker**.

| Co widzisz w `docker ps` | Co to jest |
|--------------------------|------------|
| `comfyui`, `npmplus`, `localai` | Stacki AI / proxy — **Docker** |
| **Brak** `server-ui` | Panel działa jako **usługa systemd** na hoście (domyślnie) |
| **Brak** `gpu-fan` | Agent wentylatorów — też **systemd** na hoście |

To **nie jest błąd**. Panel nie musi być kontenerem.

Sprawdzenie:

```bash
systemctl status server-ui gpu-fan
ss -tln | grep -E '8091|18090'
```

Jeśli wybrałeś instalację Server UI w **Dockerze** (opcja 2 w instalatorze), wtedy zobaczysz kontener:

```bash
docker compose --profile server-ui ps
```

---

## 3. Instalacja jednym skryptem

Na serwerze:

```bash
cd ~/cursor/ubuntu-bare-metal/stacks/server-ui
sudo ./scripts/install-control-plane.sh
```

### Menu instalatora

**1) gpu-fan** — agent sterowania wentylatorami GPU

- Działa **tylko na hoście** (root + NVML).
- **Nie instalujemy go w Dockerze** — karta wymaga bezpośredniego dostępu do sterownika NVIDIA.
- Zalecane: **Y** (tak).

**2) Server UI** — panel w przeglądarce

| Opcja | Opis |
|-------|------|
| **1 — Native** | systemd, `/opt/server-ui` (zalecane) |
| **2 — Docker** | kontener z dostępem do `docker.sock` |
| **3 — Pomiń** | tylko gpu-fan |

### Instalacja bez pytań (domyślnie: gpu-fan + server-ui native)

```bash
sudo ./scripts/install-control-plane.sh -y
```

### Tylko Server UI (bez gpu-fan)

```bash
sudo ./scripts/install-control-plane.sh --gpu-fan=no --server-ui=native
```

---

## 4. Klucz API — wpisz w panelu

**Pełna instrukcja krok po kroku:** [04a — Klucz API](04a-api-key.md)

Skrót po instalacji:

1. Na serwerze: `sudo grep ^API_KEY= /opt/control-plane/.env` — skopiuj wartość po `=`
2. W przeglądarce: `http://<IP-serwera>:8091/` → pole **API Key** → **Zapisz** → **Sprawdź klucz**
3. Lub gotowy link: `bash stacks/server-ui/scripts/show-api-key.sh` (wypisze URL z kluczem)

Jeden plik, jeden klucz — `/opt/control-plane/.env` (Server UI + gpu-fan).

**Nie używaj** `stacks/server-ui/.env` ani `GPU_FAN_AGENT_KEY` — to przestarzałe.

---

## 5. Jak uruchomić i otworzyć panel

### Native (systemd)

```bash
sudo systemctl status server-ui
sudo systemctl start server-ui    # jeśli zatrzymany
sudo systemctl restart server-ui  # po aktualizacji kodu
```

Adres (przykład):

```
http://192.168.100.90:8091/
```

### gpu-fan (jeśli zainstalowany)

```bash
sudo systemctl status gpu-fan
journalctl -u gpu-fan -f
```

### Weryfikacja API

```bash
curl -s http://127.0.0.1:8091/api/health
curl -s http://127.0.0.1:8091/api/stacks
```

### Aktualizacja kodu po zmianach w repo

```bash
cd ~/cursor/ubuntu-bare-metal/stacks/server-ui
sudo ./scripts/install.sh && sudo systemctl restart server-ui
```

---

## 6. Tryb Docker (opcjonalnie)

Jeśli w instalatorze wybrałeś **2 — Docker**:

```bash
cd ~/cursor/ubuntu-bare-metal/stacks/server-ui
docker compose --profile server-ui ps
docker compose --profile server-ui logs -f
docker compose --profile server-ui down    # stop
sudo ./scripts/install-docker.sh           # ponowna instalacja
```

gpu-fan **nadal** działa na hoście (systemd) — kontener Server UI łączy się z agentem przez `host.docker.internal:18090`.

Przełączenie z Docker na native:

```bash
docker compose --profile server-ui down
sudo ./scripts/install.sh
```

---

## 7. Troubleshooting

### Port 8091 zajęty

```bash
ss -tlnp | grep 8091
systemctl status server-ui
```

Zobacz też: [06 — gpu-fan, sekcja portów](06-gpu-fan-control.md#84-port-8090-zajęty--address-already-in-use) (podobna sytuacja — nie zwiększaj portu bez diagnozy).

### Zakładka GPU Fan nie działa

1. Czy gpu-fan działa: `systemctl status gpu-fan`
2. Czy agent odpowiada:
   ```bash
   API_KEY=$(grep ^API_KEY= /opt/control-plane/.env | cut -d= -f2)
   curl -s http://127.0.0.1:18090/api/status -H "X-API-Key: $API_KEY"
   ```
3. Ten sam klucz w panelu Server UI (pole API Key lub `?api_key=`)

### Start stacku zwraca 401 / Invalid API key

Zobacz [04a — Klucz API, sekcja 7](04a-api-key.md#7-błąd-invalid-or-missing-api-key--checklist).

### Start stacku zwraca 409

Tylko **jeden** duży workload GPU naraz (LocalAI **lub** ComfyUI **lub** vLLM). Zatrzymaj działający stack GPU przed startem drugiego.

---

## 8. Następny krok

- Zarządzaj stackami z panelu :8091
- Edytuj porty usług w kartach stacków (pole **Zapisz port**)
- Przy zmianie portu LocalAI zaktualizuj upstream w NPMPlus ręcznie

Powrót do roadmapy: [README.md](../README.md)

---

## Podsumowanie

| Pytanie | Odpowiedź |
|---------|-----------|
| Gdzie panel? | `http://<IP>:8091/` |
| Dlaczego nie w `docker ps`? | Domyślnie systemd, nie kontener |
| Klucz (Server UI + gpu-fan) | [04a — Klucz API](04a-api-key.md) · `/opt/control-plane/.env` |
| Instalacja | `sudo ./scripts/install-control-plane.sh` |