# Server UI — Docker stack manager

Własny panel do zarządzania znanymi stackami compose na **gmktec-k11**. Zastępuje Dockge i Portainer. Zawiera **przeglądarkę plików**, panel **GPU Fan** (proxy do agenta na hoście) i zarządzanie stackami.

## Dlaczego nie ma Server UI w `docker ps`?

`docker ps` pokazuje tylko **kontenery Docker**. Domyślna instalacja Server UI to **systemd na hoście** (`server-ui.service` na porcie **8091**) — nie pojawi się na liście kontenerów. To normalne.

| Usługa | Runtime | W `docker ps` |
|--------|---------|---------------|
| ComfyUI, LocalAI, vLLM, NPMPlus | Docker compose | tak |
| **Server UI** (native) | systemd → `/opt/server-ui` | **nie** |
| **gpu-fan** agent | systemd → `/opt/gpu-fan` | **nie** |

Sprawdzenie: `systemctl status server-ui` lub `docker compose --profile server-ui ps` (tryb Docker).

## Port

| Serwis | Port | URL |
|--------|------|-----|
| Server UI | **8091** | `http://HOST:8091` |
| CLI (zakładka) | — | ten sam URL, zakładka **CLI** lub `#cli` |
| Pliki (zakładka) | — | ten sam URL, zakładka **Pliki** lub `#files` |
| ComfyUI Modele (zakładka) | — | ten sam URL, zakładka **ComfyUI Modele** lub `#comfyui-models` |
| GPU Fan (zakładka) | — | ten sam URL, zakładka **GPU Fan** |
| gpu-fan agent API | **18090** | tylko localhost (proxy z Server UI) |

## Instalacja (zalecana — jeden skrypt)

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

Menu:
1. **gpu-fan** — tylko native (NVML na hoście; Docker nieobsługiwany)
2. **Server UI** — native (systemd) lub Docker (kontener)

Flagi nieinteraktywne:
```bash
sudo ./scripts/install-control-plane.sh -y
sudo ./scripts/install-control-plane.sh --gpu-fan=yes --server-ui=docker
```

### Tylko Server UI

| Tryb | Komenda |
|------|---------|
| Native (systemd) | `sudo ./scripts/install.sh` |
| Docker | `sudo ./scripts/install-docker.sh` |

Klucze API po instalacji:
```bash
bash stacks/server-ui/scripts/show-api-key.sh
```

Tutorial klucza: [`../../manual-tutorial/04a-api-key.md`](../../manual-tutorial/04a-api-key.md)

Dev: `stacks/control-plane/.env` (szablon: `stacks/control-plane/.env.example`)

Tutorial: [`../../manual-tutorial/08-server-ui-install.md`](../../manual-tutorial/08-server-ui-install.md) · CLI: [`10-server-ui-cli.md`](../../manual-tutorial/10-server-ui-cli.md) · Pliki: [`09-file-explorer.md`](../../manual-tutorial/09-file-explorer.md)

## Stacki (whitelist)

| Stack | Profil | Port UI | GPU |
|-------|--------|---------|-----|
| LocalAI | `localai` | 8070 | tak |
| ComfyUI | `comfyui` | 8188 | tak |
| vLLM | `vllm` | 8000 | tak |
| NPMPlus | `npmplus` | 81 (HTTPS) | nie |

Porty edytowalne w UI (zapis do `stacks/<name>/.env`). Szczegóły: [`../../coding-agent/SERVER-UI-PORT-CONFIG.md`](../../coding-agent/SERVER-UI-PORT-CONFIG.md)

## Update stacków

Przycisk **Update** na karcie stacka (Server UI → Stacki):

1. `docker compose pull` — pobiera najnowszy obraz (timeout do ~10 min).
2. Gdy stack **działa** — `up -d --force-recreate` (krótka przerwa w usłudze).
3. Gdy stack **zatrzymany** — tylko pull; uruchom **Start**, aby użyć nowej wersji.

Dane użytkownika są na dysku hosta (`/data/apps/*`) i **nie znikają** przy rebuildzie kontenera:

| Stack | Katalogi danych |
|-------|-----------------|
| LocalAI | `/data/apps/localai/{models,backends,configuration,images,data}` |
| ComfyUI | `/data/apps/comfyui/{models,workflows,custom_nodes,input,output,cache,storage}` |
| vLLM | `/data/apps/vllm/huggingface` (cache Hugging Face) |
| NPMPlus | `/data/apps/npmplus` |

CLI (pull bez startu): `./scripts/pull.sh` w katalogu danego stacka.

### Wdrożenie zmian Server UI (prod)

```bash
rsync -a --delete --exclude '.venv' --exclude '.env' --exclude '__pycache__' \
  ~/cursor/ubuntu-bare-metal/stacks/server-ui/ /opt/server-ui/
sudo systemctl restart server-ui
```


## ComfyUI integracja

Logika katalogu modeli, pobierania i skanu workflow jest w **Server UI**, nie w stacku ComfyUI. Stack [`../comfyui/`](../comfyui/) to tylko Docker (compose + start/pull).

| Plik | Rola |
|------|------|
| `comfyui-models.catalog.yaml` | Kuratorowana lista modeli (sekcja „Katalog repo”) |
| `comfyui_models.py` | API + joby pobierania |
| `workflow_scanner.py` | Skan workflow JSON |
| `scripts/comfyui/*.sh` | CLI pobierania (używane też przez backend) |

Po update obrazu ComfyUI: checklist w [`../comfyui/README.md`](../comfyui/README.md#checklist-po-update-obrazu).

## Bezpieczeństwo

- Odczyt statusu stacków/logów/GPU — bez klucza (LAN).
- **Start / Stop / Restart / Update** stacków, **GPU Fan**, **Pliki** (CRUD), **ComfyUI Modele** (pobieranie, anulowanie, usuwanie) i **CLI** — nagłówek `X-API-Key` (CLI: klucz w query WebSocket `?api_key=`).
- Przy `SERVER_UI_HOST=0.0.0.0` klucz jest **wymagany** przy starcie usługi.

## Tryb dev (z repo)

```bash
cp ../control-plane/.env.example ../control-plane/.env
./scripts/start.sh
```

## Struktura

```
stacks/server-ui/
├── app.py
├── comfyui_config.py          # stałe ścieżek ComfyUI (container, mounty)
├── comfyui_models.py
├── comfyui-models.catalog.yaml
├── Dockerfile
├── docker-compose.yml
├── compose_runner.py
├── stacks.yaml
├── server-ui.service
├── static/index.html
├── static/vendor/xterm/          # xterm.js dla zakładki CLI
├── cli_pty.py
└── scripts/
    ├── comfyui/                   # pobieranie modeli (CLI + backend Server UI)
    │   ├── download-model.sh
    │   ├── download-file.sh
    │   └── list-models.sh
    ├── install-control-plane.sh   # gpu-fan + server-ui (menu)
    ├── install.sh                 # native only
    ├── install-docker.sh          # docker only
    └── start.sh
```

## Dokumentacja

- [`../../manual-tutorial/08-server-ui-install.md`](../../manual-tutorial/08-server-ui-install.md)
- [`../../coding-agent/SERVER-UI-INSTALL-OPTIONS.md`](../../coding-agent/SERVER-UI-INSTALL-OPTIONS.md)
- [`../../coding-agent/DOCKER-UI-DEPLOYMENT.md`](../../coding-agent/DOCKER-UI-DEPLOYMENT.md)
- [`../../coding-agent/ADR-001-host-agent-control-plane.md`](../../coding-agent/ADR-001-host-agent-control-plane.md)