Wolfy - ComfyUI Docker Workspace

A containerized ComfyUI development environment with custom nodes, quantization backends, and multi-instance Docker architecture for AI image generation workflows.

Workspace Overview

This workspace provides a complete ComfyUI development stack with the following components:

Core Infrastructure:

• Docker-based ComfyUI deployment with CUDA 13.0 support
• Multi-instance architecture for development and production separation
• NVIDIA GPU acceleration with RTX 4090 optimization
• WireGuard VPN mesh for secure inter-service communication

AI/LLM Integration:

• Custom llama.cpp server with OpenAI-compatible API
• WebSocket support for real-time communication
• Local GGUF model hosting with quantization options

Custom Node Ecosystem:

• ComfyUI_WolfSigmas: Sigma manipulation and scheduling (44 scriptable nodes)
• ComfyUI_WolfBypass: LoRA block filtering and strength control
• ComfyUI_WolfSpectrum: KV cache management and τ-mapping
• ComfyUI_Scriptable: Code execution nodes for development
• ComfyUI_CodeMirror: Syntax-highlighted Python editor integration

Development Tools:

• Forgejo API client for Git operations
• Automated build cache management (ccache/sccache)
• Python 3.14.4 environment with system PyTorch integration
• Comprehensive testing and profiling scripts

Data Management:

• 83GB model storage with LoRA collections
• Separate input/output directories per instance
• Persistent volume mounts for development data
• KTX2 texture compression pipeline

The workspace supports both development workflows with live code mounting and production deployments with isolated configurations.

• Wolfy - ComfyUI Docker Workspace
  • Project Structure
  • 🦊 Wolfy Workspace - Stack Architecture
    • 🧠 AI/LLM Integration Details
    • 🛠️ llama.cpp Build Process
    • 🔧 Custom Nodes Architecture
    • 🐳 Multi-Instance Docker Architecture
    • 🛠️ Development & Git Integration
    • 🔒 Security Architecture
  • 🦊 Docker Architecture
    • Overview Diagram
    • Docker Services Architecture
    • Volume Mount Architecture
    • Multi-Stage Docker Build Process
    • Prerequisites
    • Building the Image
    • Running ComfyUI
    • Instance Management
    • Docker Services
    • Docker Configuration Details
      • Environment Variables
      • Docker Compose Profiles
      • Dockerfile Variants
      • Network Architecture
    • Docker Management Commands
  • Key Features
    • Custom Nodes
    • Quantization Backends
    • Optimization
  • Development Workflow
    • Environment Setup
    • Updating Dependencies
    • Running Tests
    • Compilation Cache Management
    • Docker Build Cache Optimization
    • Docker Volume Mount Strategy
  • Configuration
    • Environment Variables
    • Git Configuration
  • Remote Integration
    • WireGuard Tunnel
    • Forgejo
  • Documentation
  • Troubleshooting
    • Docker Build Issues
    • WireGuard Connection
    • GPU Issues
  • License

A ComfyUI-based AI image generation workspace with custom nodes, quantization backends, and optimized inference pipelines.

Project Structure

wolfy/
├── ComfyUI/                    # Main ComfyUI installation
├── ComfyUI_frontend/           # Frontend submodule
├── custom_nodes/              # Custom ComfyUI nodes
├── custom_nodes_3d/           # 3D-specific custom nodes
├── custom_nodes_disabled/     # Disabled custom nodes
├── vendor/                    # Third-party dependencies (gitignored)
│   ├── blender/               # Blender source
│   ├── codemirror/            # CodeMirror 6 monorepo
│   ├── deepcompressor/        # DeepCompressor quantization
│   ├── DeepSpeed/             # DeepSpeed optimization
│   ├── diffusers/             # Hugging Face diffusers
│   ├── flux2/                 # Flux2 model
│   ├── ispc/                  # Intel SPMD Compiler
│   ├── joycaption/            # JoyCaption
│   ├── libvips/               # VIPS image processing
│   ├── mistral-common/        # Mistral common utilities
│   ├── nunchaku/              # Nunchaku quantization
│   ├── oidn/                  # Intel Open Image Denoise
│   ├── pytorch/              # PyTorch source
│   ├── pyvips/               # Python VIPS bindings
│   ├── SageAttention/        # SageAttention
│   ├── sam3/                 # SAM3 segmentation
│   ├── Self-Flow/            # Self-Flow
│   ├── Spectrum/             # Spectrum sampling
│   ├── triton/               # OpenAI Triton
│   ├── unsloth/              # Unsloth training
│   ├── vllm/                 # vLLM inference
│   └── xgrammar/             # XGrammar
├── forgejo-client/            # Forgejo API client submodule
├── comfy_profiler/            # ComfyUI profiling tools
├── config/                    # Configuration files
│   ├── docker/                # Docker configurations
│   │   ├── Dockerfile         # Main Dockerfile with Blender + OptiX
│   │   ├── Dockerfile.3d      # 3D-specific Dockerfile
│   │   ├── Dockerfile.custom_blender
│   │   └── docker-compose.yml
│   ├── patches/               # Git patch files
│   ├── .gitignore
│   ├── .gitmodules
│   ├── .envrc
│   ├── .codeiumignore
│   └── requirements.txt
├── scripts/                   # Scripts
│   ├── setup/                 # Setup scripts
│   │   ├── compile_with_pytorch_cuda.py
│   │   ├── setup_diffusion_pipe_venv.sh
│   │   ├── setup_venv.sh
│   │   └── setup_xatlas.sh
│   ├── comfyui/               # ComfyUI scripts
│   │   ├── restart_comfyui.sh
│   │   ├── start_comfyui.sh
│   │   └── start_comfyui_3d.sh
│   ├── update.sh
│   └── run_sam3_test.sh
├── tests/                     # Test files
├── data/                      # JSON data files
├── wiki/                      # Documentation wiki
│   ├── comfyui/               # ComfyUI workflows and models
│   ├── optimization/          # Performance optimization
│   ├── debugging/             # Troubleshooting guides
│   ├── infrastructure/         # Docker and system setup
│   ├── benchmarking/          # Performance analysis
│   └── rtxntc/                # RTX Neural Texture Compression
├── research/                  # Research papers and studies
│   ├── low-rank-saturation-diffusion/
│   ├── nerf-artifacts/
│   ├── flux2-ablation-studies/
│   └── loraxs.md
├── input/                     # Input files
├── input-piezo/               # Piezo input
├── models/                    # Model files
├── output/                    # Output files
├── output-piezo/              # Piezo output
└── output_old/                # Old output

🦊 Wolfy Workspace - Stack Architecture

%%{init: {
  'theme': 'dark',
  'themeVariables': {
    'primaryColor': '#FF8C69',
    'primaryTextColor': '#1a1a1a',
    'primaryBorderColor': '#FF6B6B',
    'lineColor': '#FFB6C1',
    'secondaryColor': '#DDA0DD',
    'secondaryTextColor': '#1a1a1a',
    'tertiaryColor': '#F0E68C',
    'tertiaryTextColor': '#1a1a1a',
    'background': '#2d2d2d',
    'edgeLabelBackground': '#3d3d3d',
    'altBackground': '#252525',
    'gridColor': '#404040',
    'tertiaryBorderColor': '#DAA520',
    'secondaryBorderColor': '#BA55D3',
    'clusterBkg': '#353535',
    'clusterBorder': '#FF8C69',
    'nodeBkg': '#2d2d2d',
    'nodeBorder': '#FFB6C1',
    'titleColor': '#FFA07A',
    'fontSize': '16px'
  }
}}%%
graph TB
    subgraph "Host System 🦊"
        A[NVIDIA RTX 4090<br/>24GB VRAM] --> B[Ubuntu 24.04<br/>Python 3.14.4]
        B --> C[Docker Engine<br/>CUDA 13.0]
        C --> D[WireGuard VPN<br/>10.66.66.3]
        D --> E[Forgejo Git<br/>10.66.66.1:3000]
    end
    
    subgraph "AI/LLM Stack 🧠"
        F[llama.cpp Server<br/>OpenAI-Compatible API<br/>WebSocket Support] --> G[ComfyUI_WolfLlama<br/>3 Custom Nodes]
        G --> H[HTTP API<br/>Port 8080<br/>Chat Completions]
    end
    
    subgraph "Docker Compose Services 🐳"
        I[comfyui<br/>Wolfy Workspace<br/>Port 8188] --> J[comfyui-piezo<br/>Upstream ComfyUI<br/>Port 8188]
        J --> K[comfyui-3d<br/>3D Rendering<br/>Port 8189]
        K --> L[comfyui-codemirror<br/>CodeMirror Testing<br/>Port 8191]
        L --> M[create-venv<br/>Environment Setup<br/>Profile: init]
    end
    
    subgraph "Custom Nodes Ecosystem 🔧"
        N[ComfyUI_WolfSigmas<br/>44 Scriptable Nodes<br/>Sigma Manipulation] --> O[ComfyUI_WolfBypass<br/>Block Filtering<br/>LoRA Control]
        O --> P[ComfyUI_WolfSpectrum<br/>Sampling Acceleration<br/>CVPR 2026]
        P --> Q[ComfyUI_Scriptable<br/>Code Execution<br/>Security Critical]
        Q --> R[ComfyUI_CodeMirror<br/>Syntax Highlighting<br/>Editor Integration]
    end
    
    subgraph "Data & Storage 💾"
        S[models/<br/>83GB LoRAs<br/>Checkpoints] --> T[output/<br/>Generated Images]
        T --> U[output-piezo/<br/>Production Output]
        U --> V[input-piezo/<br/>Production Input]
        V --> W[models/loras-piezo/<br/>Empty for Piezo]
    end
    
    subgraph "Development Tools 🛠️"
        X[Forgejo Client<br/>Git API Integration] --> Y[Windsurf IDE<br/>AI Agent Support]
        Y --> Z[Scripts & Automation<br/>Sync & Management]
    end
    
    A --> F
    F --> I
    I --> N
    N --> S
    S --> X

🧠 AI/LLM Integration Details

llama.cpp Server:

• Location: /home/kade/wolfy/llama.cpp/ (custom build)
• API: OpenAI-compatible HTTP API on port 8080
• WebSocket Support: Built-in WebSocket transport for real-time communication
• Models: Custom GGUF models with quantization support
• Build: CUDA-enabled with RTX 4090 optimization (architecture 89)

🛠️ llama.cpp Build Process

# Update llama.cpp to latest version
cd /home/kade/wolfy/llama.cpp
git pull origin master

# Configure build with CUDA support for RTX 4090
cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="89" -DCMAKE_BUILD_TYPE=Release

# Build with 16 parallel jobs
cmake --build build -j16

# Verify server binary
ls -la /home/kade/wolfy/llama.cpp/build/bin/llama-server

Build Configuration:

• CUDA Backend: Enabled (-DGGML_CUDA=ON)
• Architecture: RTX 4090 optimized (-DCMAKE_CUDA_ARCHITECTURES="89")
• Build Type: Release optimization (-DCMAKE_BUILD_TYPE=Release)
• Parallel Jobs: 16 (-j16) for faster compilation

Server Usage:

# Start llama.cpp server
./build/bin/llama-server -m model.gguf --port 8080 --host 0.0.0.0

# Web UI: http://localhost:8080
# API Endpoint: http://localhost:8080/v1/chat/completions

ComfyUI_WolfLlama Custom Node:

• 3 Nodes: LlamaServerConnectivity, LlamaServerOptions, LlamaServerChat
• Features:
  • OpenAI-compatible chat completions (/v1/chat/completions)
  • Multimodal support (text + images)
  • JSON structured output
  • Meta chaining for workflow connections
• Integration: Direct HTTP requests to llama.cpp server (port 8080)
• Configuration: Default server URL http://127.0.0.1:8080

🔧 Custom Nodes Architecture

ComfyUI_WolfSigmas:

• Sigma Manipulation: Get, Set, PowerTransform, ClampT0, ShiftAndScale
• Additional Operations: NormalizeRange, Quantize, RespaceLogCosine, GeometricProgression
• Scriptable Nodes: 44 nodes with exec() capability (security critical)
• Documentation: README.md

ComfyUI_WolfBypass (Block Filtering):

• LoRA Control: Per-block strength filtering for Flux/Chroma models
• Block Types: double_blocks.X, single_blocks.X selective application
• Scriptable Merge: Python script-based LoRA merging (security critical)
• Documentation: README.md

ComfyUI_WolfSpectrum:

• KV Cache Management: Unified cache control for FLUX.2 Klein models
• τ-Mapping: Chebyshev polynomial extrapolation for timestep prediction
• Documentation: TAU_MAPPING_GUIDE.md

ComfyUI_Scriptable (Code Execution):

• Purpose: Scriptable nodes for local development with exec() capability
• Security: Intentionally uses exec() - disable in production via COMFYUI_DISABLE_SCRIPTABLE_NODES
• Integration: Requires ComfyUI_CodeMirror for syntax-highlighted editors
• Documentation: Built-in security warnings in source code

ComfyUI_CodeMirror (Editor):

• Function: Syntax-highlighted Python code editor
• Integration: Provides PYTHON_SCRIPT widget type
• Safety: No code execution, pure frontend component

🐳 Multi-Instance Docker Architecture

Instance Separation:

• comfyui (default): Wolfy workspace development

  • Local ./ComfyUI source code
  • Access to ./models (83GB LoRAs)
  • Uses ./output directory
  • Port Note: Uses 8188 but may conflict with comfyui-piezo

• comfyui-piezo: Production upstream instance

  • Auto-cloned upstream ComfyUI from GitHub
  • Read-only ./models access (except LoRAs)
  • Empty ./models/loras-piezo directory
  • Uses ./output-piezo and ./input-piezo
  • Port Priority: Has priority for port 8188

Resource Management:

• GPU Memory: RTX 4090 (24GB) shared across instances
• Network: Host mode for main instance, isolated for others
• Storage: Separate output directories prevent conflicts

🛠️ Development & Git Integration

Forgejo Client:

• Location: /home/kade/wolfy/forgejo-client/
• API: Forgejo REST API wrapper
• Features: Issues, labels, branches, pulls, releases, files
• Authentication: Token-based with caching

Windsurf IDE Integration:

• Agent Configuration: .windsurf/AGENTS.md (always-on context)
• Workflows: /comfyui-* slash commands for common tasks
• Skills: Network monitoring and ComfyUI analysis
• Theme: Light IDE with dark fox-themed mermaid diagrams

🔒 Security Architecture

Scriptable Nodes (Security Critical):

• WolfSigmas: 44 nodes using exec() for sigma manipulation
• WolfBypass: Scriptable LoRA merging capabilities
• Scriptable: Dedicated code execution nodes
• Protection: Environment variables to disable in production

Network Security:

• WireGuard VPN: 10.66.66.0/24 mesh network
• SSH Tunnels: Secure access to remote GPU server (inkwell)
• Container Isolation: Docker separation between instances

🦊 Docker Architecture

Overview Diagram

%%{init: {
  'theme': 'dark',
  'themeVariables': {
    'primaryColor': '#FF8C69',
    'primaryTextColor': '#1a1a1a',
    'primaryBorderColor': '#FF6B6B',
    'lineColor': '#FFB6C1',
    'secondaryColor': '#DDA0DD',
    'secondaryTextColor': '#1a1a1a',
    'tertiaryColor': '#F0E68C',
    'tertiaryTextColor': '#1a1a1a',
    'background': '#2d2d2d',
    'edgeLabelBackground': '#3d3d3d',
    'altBackground': '#252525',
    'gridColor': '#404040',
    'tertiaryBorderColor': '#DAA520',
    'secondaryBorderColor': '#BA55D3',
    'clusterBkg': '#353535',
    'clusterBorder': '#FF8C69',
    'nodeBkg': '#2d2d2d',
    'nodeBorder': '#FFB6C1',
    'titleColor': '#FFA07A',
    'fontSize': '16px'
  }
}}%%
graph TB
    subgraph "Host System 🦊"
        A[NVIDIA GPU<br/>RTX 4090] --> B[Docker Engine<br/>CUDA 13.0]
        C[WireGuard VPN<br/>10.66.66.3] --> D[Forgejo Git<br/>10.66.66.1:3000]
        E[Local Storage<br/>/home/kade/wolfy]
    end
    
    subgraph "Docker Compose 🐳"
        F[Main ComfyUI<br/>Port 8188] --> G[3D ComfyUI<br/>Port 8189]
        H[Create-Venv<br/>Profile: init] --> I[CodeMirror Test<br/>Port 8191]
    end
    
    subgraph "Container Services 🦊"
        J[ComfyUI Core<br/>Flux2-Klein] --> K[Custom Nodes<br/>Wolf Suite]
        L[Blender + OptiX<br/>GPU Ray Tracing] --> M[PyTorch CUDA<br/>FP8/W4 Quant]
        N[Volume Mounts<br/>Persistent Data] --> O[GPU Resources<br/>CUDA 13.0]
    end
    
    B --> F
    E --> N
    A --> O
    F --> J
    G --> L
    H --> M

Docker Services Architecture

%%{init: {
  'theme': 'dark',
  'themeVariables': {
    'primaryColor': '#FF8C69',
    'primaryTextColor': '#1a1a1a',
    'primaryBorderColor': '#FF6B6B',
    'lineColor': '#FFB6C1',
    'secondaryColor': '#DDA0DD',
    'secondaryTextColor': '#1a1a1a',
    'tertiaryColor': '#F0E68C',
    'tertiaryTextColor': '#1a1a1a',
    'background': '#2d2d2d',
    'edgeLabelBackground': '#3d3d3d',
    'altBackground': '#252525',
    'gridColor': '#404040',
    'tertiaryBorderColor': '#DAA520',
    'secondaryBorderColor': '#BA55D3',
    'clusterBkg': '#353535',
    'clusterBorder': '#FF8C69',
    'nodeBkg': '#2d2d2d',
    'nodeBorder': '#FFB6C1',
    'titleColor': '#FFA07A',
    'fontSize': '16px'
  }
}}%%
graph LR
    subgraph "Docker Compose Services 🐳"
        A[create-venv<br/>🔧 Setup Service] --> B[comfyui<br/>🎨 Main Service]
        A --> C[comfyui-3d<br/>🎬 3D Service]
        A --> D[comfyui-codemirror<br/>📝 Test Service]
    end
    
    subgraph "Network Configuration 🌐"
        E[Host Network<br/>Port 8188] --> F[Isolated Network<br/>Port 8189]
        F --> G[Test Network<br/>Port 8191]
    end
    
    subgraph "GPU Resources 🎮"
        H[NVIDIA Runtime<br/>CUDA 13.0] --> I[All GPUs<br/>compute,utility]
        I --> J[Graphics Support<br/>EGL/OpenGL]
    end
    
    B --> E
    C --> F
    D --> G
    B --> H
    C --> H
    D --> H

Volume Mount Architecture

%%{init: {
  'theme': 'dark',
  'themeVariables': {
    'primaryColor': '#FF8C69',
    'primaryTextColor': '#1a1a1a',
    'primaryBorderColor': '#FF6B6B',
    'lineColor': '#FFB6C1',
    'secondaryColor': '#DDA0DD',
    'secondaryTextColor': '#1a1a1a',
    'tertiaryColor': '#F0E68C',
    'tertiaryTextColor': '#1a1a1a',
    'background': '#2d2d2d',
    'edgeLabelBackground': '#3d3d3d',
    'altBackground': '#252525',
    'gridColor': '#404040',
    'tertiaryBorderColor': '#DAA520',
    'secondaryBorderColor': '#BA55D3',
    'clusterBkg': '#353535',
    'clusterBorder': '#FF8C69',
    'nodeBkg': '#2d2d2d',
    'nodeBorder': '#FFB6C1',
    'titleColor': '#FFA07A',
    'fontSize': '16px'
  }
}}%%
graph TB
    subgraph "Host Storage 🦊"
        A[venv/<br/>Python Environment] --> B[pip_cache/<br/>Package Cache]
        C[ComfyUI/<br/>Core Code] --> D[custom_nodes/<br/>Extensions]
        E[models/<br/>AI Models] --> F[output/<br/>Generated Images]
        G[textures/<br/>3D Assets] --> H[ComfyUI_frontend/<br/>UI Code]
    end
    
    subgraph "Container Mounts 🐳"
        I["/app/venv"] --> J["/root/.cache/pip"]
        K["/app/ComfyUI"] --> L["/app/ComfyUI/custom_nodes"]
        M["/app/ComfyUI/models"] --> N["/app/ComfyUI/output"]
        O["/app/textures"] --> P["/app/ComfyUI_frontend"]
    end
    
    subgraph "Service Access 🦊"
        Q[comfyui] --> R[comfyui-3d]
        R --> S[create-venv]
        S --> T[comfyui-codemirror]
    end
    
    A --> I
    B --> J
    C --> K
    D --> L
    E --> M
    F --> N
    G --> O
    H --> P
    
    Q -.-> I
    Q -.-> J
    Q -.-> K
    Q -.-> L
    Q -.-> M
    Q -.-> N
    Q -.-> O
    Q -.-> P

Multi-Stage Docker Build Process

%%{init: {
  'theme': 'dark',
  'themeVariables': {
    'primaryColor': '#FF8C69',
    'primaryTextColor': '#1a1a1a',
    'primaryBorderColor': '#FF6B6B',
    'lineColor': '#FFB6C1',
    'secondaryColor': '#DDA0DD',
    'secondaryTextColor': '#1a1a1a',
    'tertiaryColor': '#F0E68C',
    'tertiaryTextColor': '#1a1a1a',
    'background': '#2d2d2d',
    'edgeLabelBackground': '#3d3d3d',
    'altBackground': '#252525',
    'gridColor': '#404040',
    'tertiaryBorderColor': '#DAA520',
    'secondaryBorderColor': '#BA55D3',
    'clusterBkg': '#353535',
    'clusterBorder': '#FF8C69',
    'nodeBkg': '#2d2d2d',
    'nodeBorder': '#FFB6C1',
    'titleColor': '#FFA07A',
    'fontSize': '16px'
  }
}}%%
flowchart TD
    subgraph "Stage 1: Blender Builder 🎬"
        A[Ubuntu 24.04 Base] --> B[Install Build Tools<br/>cmake, ninja, gcc]
        B --> C[Extract OptiX SDK<br/>NVIDIA Ray Tracing]
        C --> D[Clone Blender Main<br/>Latest Source]
        D --> E[Build Blender<br/>OptiX + CUDA Support]
        E --> F["/opt/blender<br/>Compiled Binary"]
    end
    
    subgraph "Stage 2: ComfyUI Image 🎨"
        G[NVIDIA CUDA 13.0<br/>Ubuntu 24.04] --> H[System Dependencies<br/>Python, Git, Libraries]
        H --> I[Copy Blender<br/>From Stage 1]
        I --> J[Build comfy-aimdo<br/>CUDA Backend]
        J --> K[Build comfy-kitchen<br/>FP8 Quantization]
        K --> L[Install KTX2 Tools<br/>Texture Compression]
        L --> M[Setup ComfyUI<br/>Custom Nodes]
    end
    
    subgraph "Final Image 🦊"
        N[Multi-Stage Result] --> O[Blender + OptiX<br/>GPU Ray Tracing]
        O --> P[ComfyUI + CUDA<br/>AI Inference]
        P --> Q[Custom Backends<br/>Comfy-Kitchen]
        Q --> R[Ready to Run<br/>Docker Compose]
    end
    
    F --> I
    M --> N

Prerequisites

• NVIDIA GPU with CUDA support
• Docker with NVIDIA Container Toolkit
• Docker Compose

Building the Image

cd config/docker
docker compose build comfyui

Running ComfyUI

# Start main ComfyUI (wolfy workspace - default)
docker compose up comfyui

# Start comfyui-piezo (upstream ComfyUI with dedicated directories)
docker compose -f docker-compose.piezo.yml up comfyui-piezo

# Start with profile for venv creation
docker compose --profile init up create-venv

# Start 3D ComfyUI
docker compose --profile 3d up comfyui-3d

# Start CodeMirror test instance
docker compose -f docker-compose.codemirror.yml up comfyui-codemirror

Instance Management

# Stop specific instances
docker compose stop comfyui                    # Stop wolfy workspace
docker compose -f docker-compose.piezo.yml stop comfyui-piezo  # Stop piezo instance

# View running instances
docker ps --filter "name=comfyui"

Docker Services

• comfyui: Main wolfy workspace instance (default)

  • Container: comfyui
  • Port: 8188 (host network mode, may conflict with comfyui-piezo)
  • Purpose: Wolfy workspace development and custom node testing
  • GPU Usage: ~386MB VRAM
  • Code Source: Local ./ComfyUI directory
  • Models: Access to ./models including all LoRAs
  • Output: Uses ./output directory
  • Compose File: docker-compose.yml

• comfyui-piezo: Production upstream instance

  • Container: comfyui-piezo
  • Port: 8188 (host network mode)
  • Purpose: Production instance using upstream ComfyUI
  • GPU Usage: ~7GB VRAM (RTX 4090)
  • Code Source: https://github.com/comfyanonymous/ComfyUI (upstream)
  • Models: Read-only access to ./models (except LoRAs), uses empty ./models/loras-piezo
  • Output: Uses dedicated ./output-piezo directory
  • Input: Uses dedicated ./input-piezo directory
  • Compose File: docker-compose.piezo.yml

• comfyui-3d: 3D-specific ComfyUI with Blender + OptiX support

  • Container: comfyui-3d
  • Port: 8190 (mapped from 8189)
  • Purpose: 3D rendering and Blender workflows
  • Compose File: docker-compose.yml (requires --profile 3d)
  • Dockerfile: Dockerfile.3d

• create-venv: Python virtual environment setup service

  • Container: create-venv
  • Purpose: Creates/updates Python virtual environment
  • Compose File: docker-compose.yml (requires --profile init)

• comfyui-codemirror: CodeMirror custom node testing

  • Container: comfyui-codemirror
  • Port: 8191 (mapped from 8188)
  • Purpose: Test CodeMirror custom node development
  • Compose Files: Multiple variants available:
    • docker-compose.codemirror.yml (full workspace mount)
    • docker-compose.codemirror-simple.yml (minimal setup)

Docker Configuration Details

Environment Variables

%%{init: {
  'theme': 'dark',
  'themeVariables': {
    'primaryColor': '#FF8C69',
    'primaryTextColor': '#1a1a1a',
    'primaryBorderColor': '#FF6B6B',
    'lineColor': '#FFB6C1',
    'secondaryColor': '#DDA0DD',
    'secondaryTextColor': '#1a1a1a',
    'tertiaryColor': '#F0E68C',
    'tertiaryTextColor': '#1a1a1a',
    'background': '#2d2d2d',
    'edgeLabelBackground': '#3d3d3d',
    'altBackground': '#252525',
    'gridColor': '#404040',
    'tertiaryBorderColor': '#DAA520',
    'secondaryBorderColor': '#BA55D3',
    'clusterBkg': '#353535',
    'clusterBorder': '#FF8C69',
    'nodeBkg': '#2d2d2d',
    'nodeBorder': '#FFB6C1',
    'titleColor': '#FFA07A',
    'fontSize': '16px'
  }
}}%%
graph LR
    subgraph "NVIDIA GPU Settings 🎮"
        A[NVIDIA_VISIBLE_DEVICES<br/>all] --> B[NVIDIA_DRIVER_CAPABILITIES<br/>compute,utility,graphics]
        B --> C[CUDA Runtime<br/>13.0.2]
    end
    
    subgraph "PyTorch Configuration 🔥"
        D[TORCH_CUDA_ARCH_LIST<br/>8.9] --> E[FORCE_CUDA<br/>1]
        E --> F[TORCH_USE_CUDA_DSA<br/>0]
    end
    
    
    subgraph "Python Environment 🐍"
        J[PYTHONUNBUFFERED<br/>1] --> K[PYTHONPATH<br/>/app/ComfyUI]
        K --> L[VIRTUAL_ENV<br/>/app/venv]
    end
    
    A --> D
    D --> G
    G --> J

Docker Compose Profiles

%%{init: {
  'theme': 'dark',
  'themeVariables': {
    'primaryColor': '#FF8C69',
    'primaryTextColor': '#1a1a1a',
    'primaryBorderColor': '#FF6B6B',
    'lineColor': '#FFB6C1',
    'secondaryColor': '#DDA0DD',
    'secondaryTextColor': '#1a1a1a',
    'tertiaryColor': '#F0E68C',
    'tertiaryTextColor': '#1a1a1a',
    'background': '#2d2d2d',
    'edgeLabelBackground': '#3d3d3d',
    'altBackground': '#252525',
    'gridColor': '#404040',
    'tertiaryBorderColor': '#DAA520',
    'secondaryBorderColor': '#BA55D3',
    'clusterBkg': '#353535',
    'clusterBorder': '#FF8C69',
    'nodeBkg': '#2d2d2d',
    'nodeBorder': '#FFB6C1',
    'titleColor': '#FFA07A',
    'fontSize': '16px'
  }
}}%%
graph TB
    subgraph "Default Profile 🦊"
        A[comfyui<br/>Main Service] --> B[Host Network<br/>Port 8188]
    end
    
    subgraph "Init Profile 🔧"
        C[create-venv<br/>Setup Service] --> D[Python Environment<br/>Package Installation]
    end
    
    subgraph "3D Profile 🎬"
        E[comfyui-3d<br/>3D Service] --> F[Isolated Network<br/>Port 8189]
        F --> G[Blender + OptiX<br/>GPU Ray Tracing]
    end
    
    subgraph "Development Profiles 🛠️"
        H[codemirror<br/>Test Service] --> I[Port 8191<br/>Development]
        I --> J[cuda-fix<br/>Debug Service]
        J --> K[test<br/>CI/CD Service]
    end
    
    C --> A
    A -.-> E
    A -.-> H

Dockerfile Variants

%%{init: {
  'theme': 'dark',
  'themeVariables': {
    'primaryColor': '#FF8C69',
    'primaryTextColor': '#1a1a1a',
    'primaryBorderColor': '#FF6B6B',
    'lineColor': '#FFB6C1',
    'secondaryColor': '#DDA0DD',
    'secondaryTextColor': '#1a1a1a',
    'tertiaryColor': '#F0E68C',
    'tertiaryTextColor': '#1a1a1a',
    'background': '#2d2d2d',
    'edgeLabelBackground': '#3d3d3d',
    'altBackground': '#252525',
    'gridColor': '#404040',
    'tertiaryBorderColor': '#DAA520',
    'secondaryBorderColor': '#BA55D3',
    'clusterBkg': '#353535',
    'clusterBorder': '#FF8C69',
    'nodeBkg': '#2d2d2d',
    'nodeBorder': '#FFB6C1',
    'titleColor': '#FFA07A',
    'fontSize': '16px'
  }
}}%%
graph LR
    subgraph "Main Dockerfile 🦊"
        A[Dockerfile<br/>Multi-stage Build] --> B[Blender + OptiX<br/>GPU Ray Tracing]
        B --> C[ComfyUI + CUDA<br/>AI Inference]
        C --> D[Custom Backends<br/>Comfy-Kitchen]
    end
    
    subgraph "Specialized Variants 🎬"
        E[Dockerfile.3d<br/>3D Focus] --> F[Python 3.12<br/>LTXVideo Support]
        F --> G[Video Processing<br/>3D Workflows]
    end
    
    subgraph "Development Variants 🛠️"
        H[Dockerfile.custom_blender<br/>Custom Build] --> I[Modified Blender<br/>Experimental]
        I --> J[Dockerfile.rtxntc<br/>Texture Compression]
        J --> K[RTX Neural TC<br/>GPU Accelerated]
    end
    
    subgraph "Debug Variants 🔧"
        L[Dockerfile.cuda-fix<br/>CUDA Debug] --> M[Driver Fixes<br/>Compatibility]
        M --> N[Testing Only<br/>Debug Builds]
    end
    
    A --> E
    A --> H
    A --> L

Network Architecture

%%{init: {
  'theme': 'dark',
  'themeVariables': {
    'primaryColor': '#FF8C69',
    'primaryTextColor': '#1a1a1a',
    'primaryBorderColor': '#FF6B6B',
    'lineColor': '#FFB6C1',
    'secondaryColor': '#DDA0DD',
    'secondaryTextColor': '#1a1a1a',
    'tertiaryColor': '#F0E68C',
    'tertiaryTextColor': '#1a1a1a',
    'background': '#2d2d2d',
    'edgeLabelBackground': '#3d3d3d',
    'altBackground': '#252525',
    'gridColor': '#404040',
    'tertiaryBorderColor': '#DAA520',
    'secondaryBorderColor': '#BA55D3',
    'clusterBkg': '#353535',
    'clusterBorder': '#FF8C69',
    'nodeBkg': '#2d2d2d',
    'nodeBorder': '#FFB6C1',
    'titleColor': '#FFA07A',
    'fontSize': '16px'
  }
}}%%
graph TB
    subgraph "Host Network 🌐"
        A[localhost:8188<br/>ComfyUI Main] --> B[localhost:11434<br/>WolfLlama API]
        B --> C[10.66.66.3<br/>WireGuard VPN]
    end
    
    subgraph "Docker Networks 🐳"
        D[Host Network Mode<br/>comfyui] --> E[Isolated Network<br/>comfyui-3d]
        E --> F[Test Network<br/>comfyui-codemirror]
    end
    
    subgraph "External Services 🔗"
        G[Forgejo Git<br/>10.66.66.1:3000] --> H[Remote GPU<br/>inkwell Server]
        H --> I[Model Storage<br/>Network Volumes]
    end
    
    A --> D
    C --> G
    D -.-> E
    E -.-> F

Docker Management Commands

# Build all services
docker compose build

# Build specific service
docker compose build comfyui
docker compose build comfyui-3d

# Start services
docker compose up -d comfyui                    # Main service
docker compose --profile init up create-venv   # Setup venv
docker compose --profile 3d up comfyui-3d      # 3D service
docker compose -f docker-compose.codemirror.yml up comfyui-codemirror  # CodeMirror test

# View logs
docker compose logs comfyui
docker compose logs -f comfyui-3d               # Follow logs
docker compose logs --tail=100 create-venv      # Last 100 lines

# Stop services
docker compose down
docker compose stop comfyui
docker compose --profile 3d down

# Clean up
docker compose down --volumes                  # Remove volumes
docker compose down --rmi all                  # Remove images
docker system prune -f                          # System cleanup

Key Features

Custom Nodes

• ComfyUI_WolfBypass: LoRA merging with per-block strength control
• ComfyUI_WolfSigmas: Custom sigma scheduling
• ComfyUI_WolfSpectrum: Spectrum sampling acceleration
• ComfyUI_SVDQW4A4Linear: SVDQuant-style 4-bit quantization for Flux2-Klein

Quantization Backends

• Comfy-Kitchen: FP8 quantization backend
• Comfy-Kitchen: Alternative FP8 quantization backend
• Triton: Custom Triton kernels for SDPA and Linear+SiLU fusion

Optimization

• Flash Attention: Preferred SDPA backend
• cuDNN Attention: Fallback for certain shapes
• Triton SDPA: Custom kernel for specific attention patterns
• Fused Linear+SiLU: Single kernel for MLP operations

Development Workflow

Environment Setup

# Using direnv (recommended)
cd /home/kade/wolfy
direnv allow

# Manual activation
source config/.envrc

Updating Dependencies

# Update ComfyUI requirements
docker compose --profile init up create-venv

# Update local venv
source config/.envrc
pip install -r config/requirements.txt

Running Tests

# Run test files
python tests/test_boundary_normalization.py
python tests/tensor_shape_analyzer.py

Compilation Cache Management

The workspace uses ccache and sccache for accelerated compilation:

# View cache statistics
cache-stats

# Check cache health
./scripts/cache_manager.sh health

# Clear caches if needed
cache-clear

# Configure cache sizes
./scripts/cache_manager.sh config

Cache Configuration:

• ccache: 10GB for C/C++ compilation (AUR packages, system builds)
• sccache: 10GB for Rust compilation (Cargo projects, custom nodes)
• makepkg: ccache enabled for faster AUR package building

Cache Locations:

• ~/.cache/ccache/ - Ccache storage (created on first use)
• ~/.cache/sccache/ - Sccache storage (created on first use)

Docker Build Cache Optimization

Avoid --no-cache for System Dependencies:

The --no-cache flag defeats cache mounts and forces redownloading Ubuntu packages. Use these 2026 alternatives:

# ❌ BAD: Redownloads all Ubuntu packages
docker build --no-cache .

# ✅ GOOD: Selective cache invalidation
docker buildx build --no-cache-filter comfyui -t comfyui:latest .

# ✅ GOOD: External registry cache persistence
docker buildx build \
  --cache-from type=registry,ref=ghcr.io/your-org/comfyui:cache \
  --cache-to type=registry,ref=ghcr.io/your-org/comfyui:cache,mode=max \
  -t comfyui:latest .

# ✅ GOOD: Target specific stage rebuilds
docker buildx build --no-cache-filter system-deps -t comfyui:latest .

Multi-Stage Cache Isolation:

• system-deps stage: Ubuntu packages, system tools (cached independently)
• comfyui stage: Application code, Python packages (can be rebuilt separately)

Cache Mount Benefits:

• Persistent: Package downloads survive --no-cache for other stages
• Parallel Safe: sharing=locked prevents concurrent access issues
• No Image Bloat: Cache not stored in final image

Docker Volume Mount Strategy

Consistent Mounting Approach: All Docker services use runtime volume mounts instead of build-time COPY operations for ComfyUI and custom nodes:

# docker-compose.yml - Runtime mounts (not build-time COPY)
volumes:
  - ../../ComfyUI:/app/ComfyUI          # Live code changes
  - ../../custom_nodes:/app/ComfyUI/custom_nodes  # Development nodes
  - ../../models:/app/ComfyUI/models     # Persistent models
  - ../../output:/app/ComfyUI/output     # Generated outputs

Why Runtime Mounts:

• Live Development: Code changes reflected immediately without rebuild
• No Pointless COPY: Build-time copies would be overwritten by runtime mounts
• Consistent Strategy: All services follow the same mounting pattern
• Storage Efficiency: No duplicate storage in images and host

# View cache statistics
cache-stats

# Check cache health
./scripts/cache_manager.sh health

# Clear caches if needed
cache-clear

# Configure cache sizes
./scripts/cache_manager.sh config

Cache Configuration:

• ccache: 10GB for C/C++ compilation (AUR packages, system builds)
• sccache: 10GB for Rust compilation (Cargo projects, custom nodes)
• makepkg: ccache enabled for faster AUR package building

Cache Locations:

• ~/.cache/ccache/ - Ccache storage (created on first use)
• ~/.cache/sccache/ - Sccache storage (created on first use)

Configuration

Environment Variables

• TORCH_CUDA_ARCH_LIST: CUDA architecture list (default: 8.9)
• FORCE_CUDA: Force CUDA usage (default: 1)

Git Configuration

• .gitignore: Excludes vendor/, node_modules/, pycache, output directories
• .codeiumignore: Allowlists vendor/ for Codeium indexing
• .gitmodules: Submodule configuration

Remote Integration

WireGuard Tunnel

• Local: 10.66.66.3/24
• Remote (inkwell): 10.66.66.1/24
• Used for git operations and API access

Forgejo

• Remote: http://10.66.66.1:3000/kade/wolfy.git
• Uses WireGuard tunnel for secure access

Documentation

• CHANGELOG.md: Project changelog and release notes
• wiki/: Documentation organized by topic
• research/: Research papers and academic studies
• Key Wiki Categories:
  • ComfyUI - Workflows, models, and guidance methods
  • Optimization - Performance optimization techniques
  • Debugging - Troubleshooting guides and tools
  • Infrastructure - Docker and system setup
  • Benchmarking - Performance analysis results

Troubleshooting

Docker Build Issues

# Clean build
docker compose build --no-cache comfyui

# Check logs
docker compose logs comfyui

WireGuard Connection

# Check tunnel status
ping 10.66.66.1

# Restart WireGuard
sudo wg-quick down wg0 && sudo wg-quick up wg0

GPU Issues

# Check GPU availability
nvidia-smi

# Check Docker GPU access
docker run --rm --gpus all nvidia/cuda:13.0.2-cudnn-devel-ubuntu24.04 nvidia-smi

License

See individual component licenses in respective directories.