# ComfyUI

Node-based Stable Diffusion / Flux inference UI.

**Server:** irv-ml1 (Irvine, WireGuard-only)
**Port:** 8188 (configurable via `.env`)
**GPUs:** both (RTX 3090 + RTX A6000 both exposed; select per-workflow)
**Image:** `mmartial/comfyui-nvidia-docker`
**Native coexistence:** runs independently of `/opt/ComfyUI` (the existing native install). Migrate models by copy or move — no cross-binding.

## Path layout

All user state lives under a single host tree on `/worktank`, owned
by `lkraven:lkraven` (UID/GID 1000) so external tooling can read and
write workflow files directly. ComfyUI-Manager puts downloaded weights
into the same tree, so everything is visible on the host.

| Host path | Container path | Purpose | Restic? |
|---|---|---|---|
| `/worktank/comfyui/basedir/models/` | `/basedir/models/` | Checkpoints, loras, vae, unet, controlnet, upscale, etc. | excluded (bulk, regenerable) |
| `/worktank/comfyui/basedir/user/default/workflows/` | `/basedir/user/default/workflows/` | Workflow JSON files — **external tools edit here** | included |
| `/worktank/comfyui/basedir/custom_nodes/` | `/basedir/custom_nodes/` | ComfyUI-Manager-installed nodes | included |
| `/worktank/comfyui/basedir/input/` | `/basedir/input/` | Uploaded source images | included |
| `/worktank/comfyui/basedir/output/` | `/basedir/output/` | Generated images | excluded (regenerable) |
| `/worktank/comfyui/run/` | `/comfy/mnt` | ComfyUI source + venv + pip cache (~5 GB) | excluded (disposable) |

Standard ComfyUI model subdirs the image creates under `models/`:
`checkpoints`, `clip`, `clip_vision`, `configs`, `controlnet`,
`diffusers`, `embeddings`, `gligen`, `hypernetworks`, `loras`,
`photomaker`, `style_models`, `unet`, `upscale_models`, `vae`,
`vae_approx`.

## First-time deploy on irv-ml1

```bash
# 1. Push compose + env template from workstation
scripts/deploy-stack.sh irv-ml1 comfyui

# 2. Create basedir + run on the host (the image expects both to exist
#    as the target UID/GID before first up; it refuses to chown
#    mounted paths). One-time sudo because /worktank is root-owned.
ssh -t irv-ml1 'sudo mkdir -p /worktank/comfyui/{basedir,run} && \
                sudo chown -R lkraven:lkraven /worktank/comfyui'

# 3. Create .env and bring up. First `up` takes several minutes —
#    the image installs ~5 GB of Python packages on first boot.
ssh irv-ml1 '
  cd /opt/docker/compose/comfyui && \
  cp -n .env.example .env && \
  docker compose config >/dev/null && \
  docker compose up -d && \
  docker compose logs -f --tail=30
'
```

Once the logs settle on "Starting server" / "To see the GUI go to …",
the UI is reachable at `http://10.100.79.3:8188` (from the WG-tunnel
side). The homepage hub on ana-docker auto-discovers it via the Dozzle
agent + the homepage Docker socket integration already wired on
irv-ml1.

## Populate models

Native install lives at `/opt/ComfyUI/models/` (owned `llmuser`).
Copy or move into the container's tree — paths match 1:1:

```bash
# Example: copy one subdir at a time, preserving timestamps
ssh -t irv-ml1 'sudo -u lkraven rsync -av \
  /opt/ComfyUI/models/checkpoints/ \
  /worktank/comfyui/basedir/models/checkpoints/'
```

Repeat per subdir. `rsync -av --remove-source-files` if you want a
true move (then clean up empty source dirs). The native install will
continue to work with whatever remains under `/opt/ComfyUI/models/`.

## Editing workflows from outside the container

Workflows live as JSON under
`/worktank/comfyui/basedir/user/default/workflows/` on the host,
owned `lkraven:lkraven`. External tools running as `lkraven` can
read and write them without coordination — ComfyUI picks up file
changes on the next workflow load (no container restart needed).

## Deploy updates

```bash
# After editing compose.yaml or .env.example here
scripts/deploy-stack.sh irv-ml1 comfyui
ssh irv-ml1 'cd /opt/docker/compose/comfyui && docker compose up -d'
```

## Image version bump

```bash
# Pick a new tag from
# https://hub.docker.com/r/mmartial/comfyui-nvidia-docker/tags
ssh -t irv-ml1 '
  cd /opt/docker/compose/comfyui && \
  sed -i "s/^COMFYUI_VERSION=.*/COMFYUI_VERSION=<new-tag>/" .env && \
  docker compose pull && \
  docker compose up -d
'
```

Runtime lives at `/worktank/comfyui/run/`. For a fresh bootstrap
(force venv + pip cache rebuild against the new image):

```bash
ssh irv-ml1 '
  cd /opt/docker/compose/comfyui && \
  docker compose down && \
  rm -rf /worktank/comfyui/run/* && \
  docker compose pull && \
  docker compose up -d
'
```

User state under `/worktank/comfyui/basedir/` is untouched by either
pattern.