ComfyUI - Image Generation Service

ComfyUI is a node-based image generation UI running as a native systemd service (not Docker).

Resource URL
Web UI https://comfyui.haiven.local
API Docs https://docs.haiven.local (ComfyUI card)
API (local) http://localhost:8188
Logs journalctl -u comfyui -f

Service Details

Property Value
Service Type Native systemd
User comfyui
Install Path /opt/comfyui/ComfyUI
systemd Unit /etc/systemd/system/comfyui.service
GPU RTX 4090 (cuda:0)
Port 8188

Management Commands

# Check status
systemctl status comfyui

# Start/stop/restart
sudo systemctl start comfyui
sudo systemctl stop comfyui
sudo systemctl restart comfyui

# View logs (live)
journalctl -u comfyui -f

# View recent logs
journalctl -u comfyui -n 100

Directory Structure

/opt/comfyui/ComfyUI/           # Installation
├── main.py                     # Entry point
├── venv/                       # Python virtual environment
├── custom_nodes/               # Extensions (ComfyUI-Manager, etc.)
├── models/ → /mnt/models/image/    # Symlinked
├── output/ → /mnt/storage/generated-images/
└── input/  → /mnt/storage/images/inputs/

Model Paths

All model directories are symlinked to /mnt/models/image/:

Type Path
Checkpoints /mnt/models/image/checkpoints/
LoRAs /mnt/models/image/loras/
VAE /mnt/models/image/vae/
ControlNet /mnt/models/image/controlnet/
Embeddings /mnt/models/image/embeddings/
CLIP /mnt/models/image/clip/
UNET /mnt/models/image/unet/

Configuration Files

File Purpose
/etc/systemd/system/comfyui.service systemd service definition
/mnt/apps/docker/traefik/config/dynamic/comfyui.yml Traefik routing
/mnt/apps/docker/infrastructure/api-docs/specs/ai/comfyui.yaml OpenAPI specification
/mnt/apps/docker/infrastructure/api-docs/app/config_tier3.py API docs portal registration

API Documentation

ComfyUI is registered with the Haiven API documentation portal at https://docs.haiven.local.

Key API Endpoints:

Method Endpoint Description
GET /system_stats System info and GPU status
GET /api/models/checkpoints List available models
GET /api/models/loras List LoRA adapters
POST /prompt Submit workflow for execution
GET /queue Get queue status
GET /history/{prompt_id} Get generation details
GET /view?filename=X&type=output Download generated images
WS /ws WebSocket for real-time updates

Docker Container Access:

Since ComfyUI runs as a native systemd service (not Docker), Docker containers access it via host.docker.internal:8188. This is configured in:
- Traefik: /mnt/apps/docker/traefik/config/dynamic/comfyui.yml
- API Docs: /mnt/apps/docker/infrastructure/api-docs/app/config_tier3.py

Network Architecture

Browser → Traefik (443) → host.docker.internal:8188 → ComfyUI

Traefik routes comfyui.haiven.local to the native service via host.docker.internal.

Required iptables rule (already configured):

sudo iptables -I INPUT -i br-+ -p tcp --dport 8188 -j ACCEPT

Why Native (Not Docker)?

ComfyUI was deployed as a native systemd service instead of Docker because:

  1. Reliability - Previous Docker attempts failed due to WebSocket proxying issues
  2. Debugging - Standard Python + venv, easy to troubleshoot with journalctl
  3. GPU Access - Direct CUDA access without device mapping complexity
  4. Official Path - ComfyUI recommends native installation via comfy-cli

Installed Extensions

Version Info

Deployed: 2025-11-29
Updated: 2025-12-13 (api-docs integration fix)