# 07 — ComfyUI stack

> **Cel rozdziału:** uruchomić [ComfyUI](https://github.com/comfyanonymous/ComfyUI) w Dockerze z GPU, web UI na porcie **8188** i pustym katalogiem modeli. Modele dodasz później (checkpoint, LoRA, ComfyUI-Manager).

**Szacowany czas:**
- Pobranie obrazu Docker: 10–30 minut (pierwszy raz)
- Pierwszy start (kopia ComfyUI do `/data`): 3–10 minut

**Wymagania:** ukończone rozdziały [01](01-system-update-and-docker.md)–[05](05-localai-stack.md), mount `/data` z [04](04-vllm-stack.md)

**Kontekst:** Zamiast [Stability Matrix](https://github.com/LykosAI/StabilityMatrix) (GUI desktop) używamy ComfyUI w kontenerze — zgodnie z [03b](03b-system-tools.md) i researchiem w [`coding-agent/STABILITYMATRIX-RESEARCH.md`](../coding-agent/STABILITYMATRIX-RESEARCH.md).

---

## Spis treści

1. [ComfyUI vs Stability Matrix](#1-comfyui-vs-stability-matrix)
2. [Porty i architektura](#2-porty-i-architektura)
3. [Polityka GPU (LocalAI ↔ ComfyUI)](#3-polityka-gpu-localai--comfyui)
4. [Struktura plików stacku](#4-struktura-plików-stacku)
5. [Przygotowanie `.env`](#5-przygotowanie-env)
6. [Instalacja obrazu](#6-instalacja-obrazu)
7. [Start stacku](#7-start-stacku)
8. [Weryfikacja UI](#8-weryfikacja-ui)
9. [Zarządzanie stackiem](#9-zarządzanie-stackiem)
10. [Modele (później)](#10-modele-później)
11. [Troubleshooting](#11-troubleshooting)
12. [Następny krok](#12-następny-krok)

---

## 1. ComfyUI vs Stability Matrix

| | Stability Matrix | ComfyUI (`stacks/comfyui/`) |
|--|------------------|----------------------------|
| Typ | GUI desktop (AppImage) | **Docker, headless** |
| Wymaga pulpitu | Tak (X11/Wayland) | Nie — tylko przeglądarka |
| ComfyUI | Jeden z pakietów SM | **Bezpośrednio** w kontenerze |
| Zgodność z repo | Słaba na SSH-only | **Tak** |

SwarmUI (poprzedni UI obrazów) zostało usunięte — patrz [`SWARMUI-REMOVAL.md`](../coding-agent/SWARMUI-REMOVAL.md).

---

## 2. Porty i architektura

```mermaid
flowchart LR
    browser["Przeglądarka :8188"]
    comfyui["Kontener comfyui"]
    gpu["RTX 3090 Ti"]
    disk["/data/apps/comfyui/models"]

    browser --> comfyui
    comfyui --> gpu
    comfyui --> disk
```

| Element | Wartość |
|---------|---------|
| Obraz | `yanwk/comfyui-boot:cu126-slim` |
| Web UI | `http://127.0.0.1:8188` lub `http://192.168.100.90:8188` (LAN) |
| Modele | `/data/apps/comfyui/models` |
| Docker data | `/data/docker` |

---

## 3. Polityka GPU (LocalAI ↔ ComfyUI)

RTX 3090 Ti 24 GB — **nie uruchamiaj** dużego modelu LLM (LocalAI) i dużego checkpointu SD/Flux **równocześnie**.

Przed startem ComfyUI z generowaniem obrazów:

```bash
cd /home/tomasz-syn-grzegorza/cursor/ubuntu-bare-metal/stacks/localai
docker compose --profile localai stop localai
```

W Server UI (port 8091): Stop/Start stack `localai`, Start stack `comfyui`.

Skrypt `start.sh` ostrzega, gdy `localai` jest uruchomiony.

---

## 4. Struktura plików stacku

```
stacks/comfyui/
├── README.md
├── docker-compose.yml
├── .env.example
├── .gitignore
└── scripts/
    ├── ensure-dirs.sh
    ├── pull.sh
    └── start.sh
```

Katalogi na dysku 1 TB:

```
/data/apps/comfyui/
├── storage/          # kopia ComfyUI (pierwszy start)
├── models/
├── cache/hf-hub/
├── cache/torch-hub/
├── input/
├── output/
├── custom_nodes/
└── workflows/
```

---

## 5. Przygotowanie `.env`

```bash
cd /home/tomasz-syn-grzegorza/cursor/ubuntu-bare-metal/stacks/comfyui
cp .env.example .env
cat .env
```

Domyślne wartości:

| Zmienna | Wartość |
|---------|---------|
| `DATA_ROOT` | `/data` |
| `COMFYUI_PORT` | `8188` |
| `COMFYUI_IMAGE` | `yanwk/comfyui-boot:cu126-slim` |
| `CUDA_VISIBLE_DEVICES` | `0` |

---

## 6. Instalacja obrazu

```bash
./scripts/pull.sh
```

Oczekiwany wynik: pobranie warstw `yanwk/comfyui-boot:cu126-slim` (kilka GB).

---

## 7. Start stacku

```bash
./scripts/start.sh
```

Skrypt:

1. Sprawdza mount `/data`
2. Tworzy katalogi (`ensure-dirs.sh`)
3. Ostrzega, jeśli `localai` działa
4. `docker compose --profile comfyui up -d`

Pierwszy start kopiuje ComfyUI do `/data/apps/comfyui/storage/` — obserwuj logi:

```bash
docker compose --profile comfyui logs -f comfyui
```

---

## 8. Weryfikacja UI

```bash
docker compose --profile comfyui ps
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8188/
```

Oczekiwane: kontener `healthy` lub `running`, HTTP **200** (może zająć ~3 min przy pierwszym starcie).

W przeglądarce (z sieci lokalnej):

```
http://192.168.100.90:8188
```

Tunel SSH z laptopa:

```bash
ssh -L 8188:127.0.0.1:8188 tomasz-syn-grzegorza@gmktec-k11
# potem http://localhost:8188
```

GPU:

```bash
nvidia-smi
```

---

## 9. Zarządzanie stackiem

```bash
docker compose --profile comfyui ps
docker compose --profile comfyui logs -f comfyui
docker compose --profile comfyui restart comfyui
docker compose --profile comfyui down
```

Powrót do LocalAI:

```bash
cd ../comfyui && docker compose --profile comfyui stop comfyui
cd ../localai && docker compose --profile localai start localai
```

---

## 10. Modele

Compose **nie pobiera** modeli automatycznie.

### Server UI (zalecane)

1. Panel **Server UI** (`http://<IP>:8091`) → zakładka **ComfyUI Modele**
2. Wpisz API Key (rozdział 08) → wybierz model → **Pobierz**
3. Pliki lądują w `/data/apps/comfyui/models/` (bind mount — przetrwają restart kontenera)

**Sekcja „Wymagane przez workflow”** skanuje `/data/apps/comfyui/workflows/*.json` i pokazuje brakujące pliki (checkpoint, LoRA, VAE itd.). URL pobierania jest brany z ComfyUI-Manager, gdy model nie ma wpisu w `stacks/server-ui/comfyui-models.catalog.yaml`. Zapis workflow w ComfyUI (`:8188`) automatycznie aktualizuje listę po odświeżeniu Server UI.

Przykład testowy: `cp manual-tutorial/examples/comfyui/example-sdxl-refiner.api.json /data/apps/comfyui/workflows/`

### Skrypty CLI

```bash
cd stacks/server-ui/scripts/comfyui
./list-models.sh
./download-model.sh <catalog-id>
```

Katalog: `stacks/server-ui/comfyui-models.catalog.yaml`

### Inne opcje

1. **ComfyUI-Manager** w UI ComfyUI (`:8188`) — modele spoza katalogu repo
2. Ręcznie — pliki `.safetensors` / `.ckpt` do `/data/apps/comfyui/models/checkpoints/`

Opcjonalnie w `.env`: `HF_TOKEN`, `CIVITAI_TOKEN` (dla wybranych wpisów katalogu).

Szacunki VRAM (przy zatrzymanym LocalAI):

| Model | VRAM (orientacyjnie) |
|-------|----------------------|
| SD 1.5 | ~4–6 GB |
| SDXL | ~8–12 GB |
| Flux | ~12–20 GB |

---

## 11. Troubleshooting

### HTTP nie odpowiada / 000

Pierwszy start trwa dłużej — sprawdź logi:

```bash
docker compose --profile comfyui logs --tail 80 comfyui
```

### `CUDA out of memory`

Zatrzymaj LocalAI i inne workloady GPU:

```bash
docker ps --format '{{.Names}}'
nvidia-smi
```

### Brak `/data`

```bash
mountpoint /data
# jeśli nie — rozdział 04, część A
```

### Kontener restartuje się w pętli

Sprawdź, czy NVIDIA Container Toolkit działa (rozdział 03):

```bash
docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu22.04 nvidia-smi
```

---

## 12. Następny krok

Po przejściu weryfikacji:

1. Zgłoś w rozmowie z Cursorem, że krok 07 jest gotowy.
2. Pobierz pierwszy checkpoint (SD 1.5 lub SDXL) — osobny krok.
3. Później: rozdział **08 — firewall i hardening**.

---

## Checklist

- [ ] `.env` utworzony z `.env.example`
- [ ] `docker compose --profile comfyui pull` — obraz pobrany
- [ ] LocalAI zatrzymany przed pierwszym testem generowania (opcjonalnie przy samym starcie UI)
- [ ] `./scripts/start.sh` — kontener `comfyui` running
- [ ] `curl http://127.0.0.1:8188/` — HTTP 200
- [ ] UI otwiera się w przeglądarce na `:8188`
- [ ] Katalogi istnieją pod `/data/apps/comfyui/`