ComfyUI — Wellysa Custom Deployment

Custom ComfyUI fork with REST API server, database persistence, nginx reverse proxy, and Railway deployment support for production-grade AI inference workflows.

Tech Stack

• Python 3.13 — Core runtime
• ComfyUI — Visual node-based diffusion model engine
• nginx — Reverse proxy with optional basic auth (htpasswd)
• SQLAlchemy + Alembic — Database ORM and migrations
• PyTorch — Deep learning framework (GPU/CPU support)
• Docker — Containerized deployment
• Railway — Cloud deployment platform (see RAILWAY_SETUP.md)

Features

Core ComfyUI Capabilities

• Node-based visual interface for Stable Diffusion workflows
• Support for multiple model architectures (SD1.x, SDXL, Flux, SD3, etc.)
• Video generation with Stable Video Diffusion (models pre-downloaded at build time)
• LoRA, ControlNet, inpainting, upscaling, area composition
• Asynchronous queue system with smart memory management

Wellysa Custom Extensions

• REST API Server (api_server/) — Programmatic access to ComfyUI workflows
• Database Persistence (alembic_db/) — Store workflow metadata, job history, user data
• nginx Integration — Reverse proxy with optional authentication
• Railway Deployment — One-click cloud deployment with environment config
• Pre-downloaded Models — Essential video models (SVD) included in Docker image

Quick Start

Docker (Recommended)

1. Build the image:

   docker build -t wellysa-comfyui .

2. Run the container:

   docker run -p 8000:8000 -v $(pwd)/models:/app/models wellysa-comfyui

3. Access the UI:

   • Web interface: http://localhost:8000
   • API server: http://localhost:8000/api (unverified — check api_server/routes/)

Local Development

1. Clone and install dependencies:

   git clone <repository-url>
   cd comfy_UI
   pip install -r requirements.txt

2. Download models:

   chmod +x scripts/download_essential_models.sh scripts/download_video_models.sh
   ./scripts/download_essential_models.sh
   ./scripts/download_video_models.sh

3. Run database migrations:

   alembic upgrade head

4. Start the application:

   ./start.sh

   (Note: start.sh starts both nginx and ComfyUI — see script for details)

Railway Deployment

See RAILWAY_SETUP.md for detailed instructions on deploying to Railway's cloud platform.

Architecture

comfy_UI/
├── api_server/          # REST API layer
│   ├── routes/          # API endpoints (internal + public)
│   ├── services/        # Business logic
│   └── utils/           # Helpers and utilities
├── alembic_db/          # Database migrations (Alembic)
│   └── versions/        # Migration scripts
├── app/                 # Main application
│   ├── assets/          # Static files (API schemas, DB queries)
│   └── database/        # Database models and connections
├── comfy/               # ComfyUI core inference engine
├── blueprints/          # Flask/FastAPI blueprints (unverified)
├── models/              # Model weights storage
│   ├── checkpoints/     # Stable Diffusion checkpoints
│   ├── vae/             # VAE models
│   ├── loras/           # LoRA weights
│   └── ...              # ControlNet, upscalers, etc.
├── nginx.conf           # Reverse proxy configuration
├── start.sh             # Startup script (nginx + ComfyUI)
└── Dockerfile           # Production container definition

API Endpoints

(Unverified — confirm with team by reviewing api_server/routes/)

The REST API provides programmatic access to ComfyUI workflows. Common endpoints likely include:

• POST /api/queue — Submit a workflow for processing
• GET /api/history — Retrieve job history
• GET /api/system_stats — System resource usage
• Internal routes under /api/internal/ — Admin/monitoring endpoints

Run the server and inspect api_server/routes/ for the complete API specification.

Configuration

Environment Variables

• PORT — HTTP server port (default: set by Railway or start.sh)
• PYTHONUNBUFFERED=1 — Immediate stdout/stderr flushing (set in Dockerfile)
• (Additional vars TBD — check start.sh or .env files)

Model Paths

Place model files in the following directories:

• Checkpoints: models/checkpoints/ (e.g., SD1.5, SDXL, Flux)
• VAE: models/vae/
• LoRA: models/loras/
• ControlNet: models/controlnet/
• Upscalers: models/upscale_models/

See extra_model_paths.yaml.example to configure additional model search paths.

nginx & Authentication

Edit nginx.conf to configure:

• Port bindings and proxy settings
• Basic auth (uses htpasswd — generate with: htpasswd -c .htpasswd <username>)
• SSL/TLS certificates (if deploying with HTTPS)

Database

This fork includes Alembic-managed database schema for:

• Workflow metadata persistence
• Job queue history
• User/API authentication (unverified)

Run migrations:

alembic upgrade head  # Apply all pending migrations
alembic downgrade -1  # Rollback last migration

Database connection: (Unverified — check app/database/ for connection strings)

Keyboard Shortcuts

Keybind	Action
Ctrl + Enter	Queue workflow
Ctrl + Shift + Enter	Queue as first
Ctrl + Alt + Enter	Cancel generation
Ctrl + S	Save workflow
Ctrl + O	Load workflow
Ctrl + A	Select all nodes
Space (hold)	Pan canvas
Ctrl + Z / Ctrl + Y	Undo/Redo
Delete	Delete selected nodes

Full list available in upstream ComfyUI docs.

Development

Running Tests

(Unverified — confirm test setup)

pytest                        # Run all tests
pytest api_server/tests/      # API tests only

Code Quality

• Linting: ruff check . (see .github/workflows/ruff.yml)
• Type checking: (TBD — check if mypy configured)

GPU Support

NVIDIA (Recommended)

pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130

AMD (Linux)

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm7.1

CPU-only

Run with --cpu flag (slow, not recommended for production).

See upstream ComfyUI GPU docs for detailed instructions on AMD/Intel/Apple Silicon setups.

Known Issues & Limitations

• Railway PORT binding: Ensure start.sh respects the $PORT environment variable set by Railway
• Model size: Docker image includes pre-downloaded SVD models (~several GB) — increase storage if deploying to constrained environments
• Database schema: Schema is evolving — always run alembic upgrade head after pulling updates

Support & Contributing

• Issues: Report bugs via GitHub Issues
• Upstream ComfyUI: comfyanonymous/ComfyUI
• Wellysa Team: (Confirm internal contact/Slack channel if applicable)

License

Inherits license from upstream ComfyUI (check LICENSE file). Custom Wellysa extensions (unverified — confirm licensing for api_server/ and database code).

---

Built by Wellysa | Powered by ComfyUI