Patrick Plate
c662a5237b
Option A: Add lifespan context manager to server.py - _ping_comfyui(): async health check against /system_stats - check_and_start_comfyui(): ping on startup; if down, launches ComfyUI via subprocess.Popen from COMFYUI_DIR (.venv/bin/python main.py) with HSA_OVERRIDE_GFX_VERSION=11.0.0 injected for AMD ROCm - Polls up to 30s for readiness after auto-start - New env var: COMFYUI_DIR (default ~/ComfyUI) - FastMCP lifespan= wired in; 34/34 tests still passing Option B: Add comfyui.service systemd user service file - Install: cp mcp/mcp-image-gen/comfyui.service ~/.config/systemd/user/ - Enable: systemctl --user enable --now comfyui - Sets HSA_OVERRIDE_GFX_VERSION=11.0.0, WorkingDirectory=%h/ComfyUI - Restart=on-failure, logs via journald docs: Update mcp-image-gen-ComfyUI-Setup.md - New Step 4: systemd service install + linger instructions - Step 5: manual start (moved from old Step 4) - Step 6/7 renumbered; COMFYUI_DIR env var documented - Architecture diagram added; troubleshooting rows updated
184 lines
5.6 KiB
Markdown
184 lines
5.6 KiB
Markdown
# ⚙️ ComfyUI Setup Guide (AMD ROCm)
|
||
|
||
This guide covers installing ComfyUI with FLUX.1-schnell on a Fedora Linux system with an AMD GPU.
|
||
|
||
## Prerequisites
|
||
|
||
- AMD GPU with ROCm support (tested: RX 7900 XTX)
|
||
- Fedora Linux (tested: Fedora 43 / kernel 6.19)
|
||
- Python 3.11+
|
||
- ~15GB free disk space (model weights)
|
||
- HuggingFace account with FLUX license accepted
|
||
|
||
## Step 1: Install ComfyUI
|
||
|
||
ComfyUI is **not on PyPI** — must be cloned from source:
|
||
|
||
```bash
|
||
cd ~
|
||
git clone https://github.com/comfyanonymous/ComfyUI
|
||
cd ComfyUI
|
||
python -m venv .venv
|
||
source .venv/bin/activate
|
||
|
||
# Install PyTorch ROCm build (CRITICAL for AMD GPUs)
|
||
pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm6.2
|
||
|
||
# Install ComfyUI dependencies
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
## Step 2: Download FLUX.1-schnell
|
||
|
||
FLUX.1-schnell is **gated on HuggingFace** — you must:
|
||
1. Create a HuggingFace account
|
||
2. Accept the FLUX.1-schnell license at https://huggingface.co/black-forest-labs/FLUX.1-schnell
|
||
3. Generate an access token at https://huggingface.co/settings/tokens
|
||
|
||
```bash
|
||
# Install huggingface_hub
|
||
pip install huggingface_hub
|
||
|
||
# Download model (requires HF token)
|
||
huggingface-cli download black-forest-labs/FLUX.1-schnell \
|
||
flux1-schnell.safetensors \
|
||
--local-dir ~/ComfyUI/models/checkpoints \
|
||
--token YOUR_HF_TOKEN_HERE
|
||
```
|
||
|
||
## Step 3: Download VAE and CLIP Models
|
||
|
||
FLUX.1-schnell also requires VAE and CLIP text encoders:
|
||
|
||
```bash
|
||
# VAE
|
||
huggingface-cli download black-forest-labs/FLUX.1-schnell \
|
||
ae.safetensors \
|
||
--local-dir ~/ComfyUI/models/vae
|
||
|
||
# CLIP models (T5 and CLIP-L)
|
||
huggingface-cli download comfyanonymous/flux_text_encoders \
|
||
t5xxl_fp8_e4m3fn.safetensors clip_l.safetensors \
|
||
--local-dir ~/ComfyUI/models/clip
|
||
```
|
||
|
||
## Step 4: Install the systemd User Service (Recommended)
|
||
|
||
Installing ComfyUI as a systemd user service ensures it starts automatically on login and restarts on failure.
|
||
|
||
```bash
|
||
# Copy the bundled service file to the systemd user directory
|
||
mkdir -p ~/.config/systemd/user
|
||
cp ~/pi_mcps/mcp/mcp-image-gen/comfyui.service ~/.config/systemd/user/comfyui.service
|
||
|
||
# Reload systemd, enable + start the service
|
||
systemctl --user daemon-reload
|
||
systemctl --user enable --now comfyui
|
||
|
||
# Verify it is running
|
||
systemctl --user status comfyui
|
||
```
|
||
|
||
> ⚠️ `HSA_OVERRIDE_GFX_VERSION=11.0.0` is already set in the service file — it is mandatory for RX 7900 XTX on ROCm. Without it, model loading fails silently.
|
||
|
||
### Enable lingering (start ComfyUI even without a login session)
|
||
|
||
```bash
|
||
loginctl enable-linger $USER
|
||
```
|
||
|
||
This ensures the service starts at boot even before you log in — recommended for headless / homelab setups.
|
||
|
||
### Managing the service
|
||
|
||
```bash
|
||
# Follow live logs
|
||
journalctl --user -u comfyui -f
|
||
|
||
# Restart after model changes
|
||
systemctl --user restart comfyui
|
||
|
||
# Stop temporarily
|
||
systemctl --user stop comfyui
|
||
|
||
# Disable autostart
|
||
systemctl --user disable comfyui
|
||
```
|
||
|
||
## Step 5: Manual Start (without systemd)
|
||
|
||
If you prefer to start ComfyUI manually (e.g. for debugging):
|
||
|
||
```bash
|
||
cd ~/ComfyUI
|
||
|
||
# AMD GPU REQUIRES this environment variable
|
||
HSA_OVERRIDE_GFX_VERSION=11.0.0 \
|
||
nohup .venv/bin/python main.py --listen --port 8188 > /tmp/comfyui.log 2>&1 &
|
||
|
||
echo "ComfyUI PID: $!"
|
||
```
|
||
|
||
## Step 6: Verify ComfyUI is Running
|
||
|
||
```bash
|
||
curl http://localhost:8188/system_stats
|
||
# Should return JSON with GPU info
|
||
```
|
||
|
||
## Step 7: Configure mcp-image-gen
|
||
|
||
```bash
|
||
cd /home/pplate/pi_mcps/mcp/mcp-image-gen
|
||
|
||
# Environment variables (set in .roo/mcp.json or shell):
|
||
# COMFYUI_URL=http://localhost:8188 — ComfyUI API endpoint
|
||
# IMAGE_OUTPUT_DIR=~/Pictures/mcp-generated — where generated images are saved
|
||
# COMFYUI_TIMEOUT=120 — max wait time (seconds) per image
|
||
# COMFYUI_DIR=~/ComfyUI — path to ComfyUI install (used by auto-start)
|
||
```
|
||
|
||
### Auto-start behaviour
|
||
|
||
`mcp-image-gen` includes a **startup health check** in its lifespan. Every time the MCP server starts it:
|
||
|
||
1. Pings `http://localhost:8188/system_stats`
|
||
2. **If reachable** — logs `ComfyUI is already running ✓` and proceeds normally.
|
||
3. **If not reachable** — attempts to launch ComfyUI as a background subprocess from `COMFYUI_DIR` using `.venv/bin/python main.py --listen --port 8188` with `HSA_OVERRIDE_GFX_VERSION=11.0.0` injected automatically.
|
||
4. Polls up to 30 s for ComfyUI to become ready.
|
||
|
||
With the systemd service enabled, step 3 is never needed in practice — but the check acts as a safety net.
|
||
|
||
## Performance
|
||
|
||
| GPU | Model | Resolution | Steps | Time |
|
||
|---|---|---|---|---|
|
||
| AMD RX 7900 XTX | FLUX.1-schnell | 1024×1024 | 4 | ~8s |
|
||
| AMD RX 7900 XTX | FLUX.1-schnell | 1280×512 | 4 | ~7s |
|
||
|
||
## Architecture Overview
|
||
|
||
```
|
||
Boot
|
||
└─ systemd --user (comfyui.service)
|
||
└─ ComfyUI at localhost:8188
|
||
|
||
VS Code / Roo Code
|
||
└─ mcp-image-gen MCP server (stdio)
|
||
├─ lifespan startup: ping localhost:8188
|
||
│ └─ if down: subprocess.Popen ComfyUI, wait ≤30s
|
||
└─ tools: generate_image, list_available_models, …
|
||
```
|
||
|
||
## Troubleshooting
|
||
|
||
| Problem | Solution |
|
||
|---|---|
|
||
| `HTTP 401` downloading model | Accept FLUX license on HuggingFace first |
|
||
| GPU not detected | Ensure `HSA_OVERRIDE_GFX_VERSION=11.0.0` is set |
|
||
| `Connection refused` from mcp-image-gen | Check `systemctl --user status comfyui`; or set `COMFYUI_DIR` so auto-start can locate the install |
|
||
| Slow generation (>60s) | ComfyUI may be running on CPU — check ROCm install and `HSA_OVERRIDE_GFX_VERSION` |
|
||
| Ollama image gen | As of April 2026: macOS-only, not available on Linux |
|
||
| Auto-start logs | `journalctl --user -u comfyui -f` or check mcp-image-gen server logs |
|
||
| Service not starting at boot | Run `loginctl enable-linger $USER` to enable session-less startup |
|