feat: add Arty configuration and Claude Code documentation

- Add arty.yml for repository management with environment profiles (prod/dev/minimal) - Add CLAUDE.md with comprehensive architecture and usage documentation - Add comfyui_models.yaml for ComfyUI model configuration - Include deployment scripts for model linking and dependency installation - Document all git repositories (ComfyUI + 10 custom nodes) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-22 02:50:36 +01:00
parent c9b01eef68
commit 2207d60f98
3 changed files with 891 additions and 0 deletions
--- a/arty.yml
+++ b/arty.yml
@@ -0,0 +1,212 @@
+name: "RunPod AI Model Orchestrator"
+version: "2.0.0"
+description: "Process-based AI model orchestrator for RunPod GPU instances with ComfyUI integration"
+author: "valknar@pivoine.art"
+license: "MIT"
+
+# Git repositories to clone for a fresh RunPod deployment
+references:
+  # ComfyUI base installation
+  - url: https://github.com/comfyanonymous/ComfyUI.git
+    into: /workspace/ComfyUI
+    description: "ComfyUI - Node-based interface for image/video/audio generation"
+
+  # ComfyUI Essential Custom Nodes
+  - url: https://github.com/ltdrdata/ComfyUI-Manager.git
+    into: /workspace/ComfyUI/custom_nodes/ComfyUI-Manager
+    description: "ComfyUI Manager - Install/manage custom nodes and models"
+    essential: true
+
+  - url: https://github.com/Kosinkadink/ComfyUI-VideoHelperSuite.git
+    into: /workspace/ComfyUI/custom_nodes/ComfyUI-VideoHelperSuite
+    description: "Video operations and processing"
+    essential: true
+
+  - url: https://github.com/Kosinkadink/ComfyUI-AnimateDiff-Evolved.git
+    into: /workspace/ComfyUI/custom_nodes/ComfyUI-AnimateDiff-Evolved
+    description: "AnimateDiff for video generation"
+    essential: true
+
+  - url: https://github.com/cubiq/ComfyUI_IPAdapter_plus.git
+    into: /workspace/ComfyUI/custom_nodes/ComfyUI_IPAdapter_plus
+    description: "IP-Adapter for style transfer"
+    essential: true
+
+  - url: https://github.com/ltdrdata/ComfyUI-Impact-Pack.git
+    into: /workspace/ComfyUI/custom_nodes/ComfyUI-Impact-Pack
+    description: "Auto face enhancement and detailer"
+    essential: true
+
+  # ComfyUI Optional Custom Nodes
+  - url: https://github.com/kijai/ComfyUI-CogVideoXWrapper.git
+    into: /workspace/ComfyUI/custom_nodes/ComfyUI-CogVideoXWrapper
+    description: "CogVideoX integration for text-to-video"
+    essential: false
+
+  - url: https://github.com/ltdrdata/ComfyUI-Inspire-Pack.git
+    into: /workspace/ComfyUI/custom_nodes/ComfyUI-Inspire-Pack
+    description: "Additional inspiration tools"
+    essential: false
+
+  - url: https://github.com/Kosinkadink/ComfyUI-Advanced-ControlNet.git
+    into: /workspace/ComfyUI/custom_nodes/ComfyUI-Advanced-ControlNet
+    description: "Advanced ControlNet features"
+    essential: false
+
+  - url: https://github.com/MrForExample/ComfyUI-3D-Pack.git
+    into: /workspace/ComfyUI/custom_nodes/ComfyUI-3D-Pack
+    description: "3D asset generation"
+    essential: false
+
+  - url: https://github.com/MixLabPro/comfyui-sound-lab.git
+    into: /workspace/ComfyUI/custom_nodes/comfyui-sound-lab
+    description: "MusicGen and Stable Audio integration"
+    essential: false
+
+# Environment profiles for selective repository management
+envs:
+  # Production: Only essential components
+  prod:
+    - /workspace/ai
+    - /workspace/ComfyUI
+    - /workspace/ComfyUI/custom_nodes/ComfyUI-Manager
+    - /workspace/ComfyUI/custom_nodes/ComfyUI-VideoHelperSuite
+    - /workspace/ComfyUI/custom_nodes/ComfyUI-AnimateDiff-Evolved
+    - /workspace/ComfyUI/custom_nodes/ComfyUI_IPAdapter_plus
+    - /workspace/ComfyUI/custom_nodes/ComfyUI-Impact-Pack
+
+  # Development: All repositories including optional nodes
+  dev:
+    - /workspace/ai
+    - /workspace/ComfyUI
+    - /workspace/ComfyUI/custom_nodes/ComfyUI-Manager
+    - /workspace/ComfyUI/custom_nodes/ComfyUI-VideoHelperSuite
+    - /workspace/ComfyUI/custom_nodes/ComfyUI-AnimateDiff-Evolved
+    - /workspace/ComfyUI/custom_nodes/ComfyUI_IPAdapter_plus
+    - /workspace/ComfyUI/custom_nodes/ComfyUI-Impact-Pack
+    - /workspace/ComfyUI/custom_nodes/ComfyUI-CogVideoXWrapper
+    - /workspace/ComfyUI/custom_nodes/ComfyUI-Inspire-Pack
+    - /workspace/ComfyUI/custom_nodes/ComfyUI-Advanced-ControlNet
+    - /workspace/ComfyUI/custom_nodes/ComfyUI-3D-Pack
+    - /workspace/ComfyUI/custom_nodes/comfyui-sound-lab
+
+  # Minimal: Only orchestrator and ComfyUI base
+  minimal:
+    - /workspace/ai
+    - /workspace/ComfyUI
+    - /workspace/ComfyUI/custom_nodes/ComfyUI-Manager
+
+# Deployment scripts for RunPod instances
+scripts:
+  # Initial setup
+  setup/full: |
+    cd /workspace/ai
+    cp .env.example .env
+    echo "Edit .env and set HF_TOKEN, then run: ansible-playbook playbook.yml"
+
+  setup/essential: |
+    cd /workspace/ai
+    cp .env.example .env
+    echo "Edit .env and set HF_TOKEN, then run: ansible-playbook playbook.yml --tags comfyui-essential"
+
+  # Model linking (run after models are downloaded)
+  models/link-comfyui: |
+    cd /workspace/ComfyUI/models/diffusers
+    ln -sf /workspace/huggingface_cache/models--black-forest-labs--FLUX.1-schnell FLUX.1-schnell
+    ln -sf /workspace/huggingface_cache/models--black-forest-labs--FLUX.1-dev FLUX.1-dev
+    ln -sf /workspace/huggingface_cache/models--stabilityai--stable-diffusion-xl-base-1.0 stable-diffusion-xl-base-1.0
+    ln -sf /workspace/huggingface_cache/models--stabilityai--stable-diffusion-xl-refiner-1.0 stable-diffusion-xl-refiner-1.0
+    ln -sf /workspace/huggingface_cache/models--stabilityai--stable-diffusion-3.5-large stable-diffusion-3.5-large
+    cd /workspace/ComfyUI/models/clip_vision
+    ln -sf /workspace/huggingface_cache/models--openai--clip-vit-large-patch14 clip-vit-large-patch14
+    ln -sf /workspace/huggingface_cache/models--laion--CLIP-ViT-bigG-14-laion2B-39B-b160k CLIP-ViT-bigG-14
+    ln -sf /workspace/huggingface_cache/models--google--siglip-so400m-patch14-384 siglip-so400m-patch14-384
+    cd /workspace/ComfyUI/models/diffusion_models
+    ln -sf /workspace/huggingface_cache/models--THUDM--CogVideoX-5b CogVideoX-5b
+    ln -sf /workspace/huggingface_cache/models--stabilityai--stable-video-diffusion-img2vid stable-video-diffusion-img2vid
+    ln -sf /workspace/huggingface_cache/models--stabilityai--stable-video-diffusion-img2vid-xt stable-video-diffusion-img2vid-xt
+    echo "Models linked to ComfyUI"
+
+  # Service management
+  services/start: bash /workspace/ai/scripts/start-all.sh
+  services/stop: bash /workspace/ai/scripts/stop-all.sh
+  services/restart: bash /workspace/ai/scripts/stop-all.sh && bash /workspace/ai/scripts/start-all.sh
+
+  # Dependency installation
+  deps/comfyui-nodes: |
+    pip3 install -r /workspace/ComfyUI/custom_nodes/ComfyUI-Manager/requirements.txt
+    pip3 install -r /workspace/ComfyUI/custom_nodes/ComfyUI-VideoHelperSuite/requirements.txt
+    pip3 install 'numpy<2.0.0' --force-reinstall
+    echo "Custom node dependencies installed"
+
+  # Ansible provisioning shortcuts
+  ansible/base: cd /workspace/ai && ansible-playbook playbook.yml --tags base,python,dependencies
+  ansible/vllm: cd /workspace/ai && ansible-playbook playbook.yml --tags models
+  ansible/comfyui: cd /workspace/ai && ansible-playbook playbook.yml --tags comfyui,comfyui-essential
+  ansible/comfyui-all: cd /workspace/ai && ansible-playbook playbook.yml --tags comfyui,comfyui-models-all,comfyui-nodes
+  ansible/full: cd /workspace/ai && ansible-playbook playbook.yml
+
+  # Health checks
+  health/orchestrator: curl http://localhost:9000/health
+  health/comfyui: curl http://localhost:8188
+  health/vllm: curl http://localhost:8000/health
+
+  # System checks
+  check/gpu: nvidia-smi
+  check/disk: df -h /workspace
+  check/models: du -sh /workspace/huggingface_cache
+  check/cache: find /workspace/huggingface_cache -type d -name 'models--*' -maxdepth 1
+
+# Deployment notes
+notes: |
+  RunPod AI Model Orchestrator - Quick Start
+
+  1. Fresh Deployment:
+     - Clone repositories: arty sync --env prod
+     - Configure environment: cd /workspace/ai && cp .env.example .env
+     - Set HF_TOKEN in .env file
+     - Run Ansible: ansible-playbook playbook.yml --tags comfyui-essential
+     - Link models: arty run models/link-comfyui
+     - Install node deps: arty run deps/comfyui-nodes
+     - Start services: arty run services/start
+
+  2. Model Downloads:
+     - Essential (~80GB): ansible-playbook playbook.yml --tags comfyui-essential
+     - All models (~137GB): ansible-playbook playbook.yml --tags comfyui-models-all
+
+  3. Service Management:
+     - Start: arty run services/start
+     - Stop: arty run services/stop
+     - Restart: arty run services/restart
+
+  4. Health Checks:
+     - Orchestrator: arty run health/orchestrator
+     - ComfyUI: arty run health/comfyui
+     - vLLM: arty run health/vllm
+
+  5. Environment Profiles:
+     - Production (essential only): arty sync --env prod
+     - Development (all nodes): arty sync --env dev
+     - Minimal (orchestrator + ComfyUI only): arty sync --env minimal
+
+  6. Important Files:
+     - Configuration: /workspace/ai/playbook.yml
+     - Model registry: /workspace/ai/model-orchestrator/models.yaml
+     - Environment: /workspace/ai/.env
+     - Services: /workspace/ai/scripts/*.sh
+
+  7. Ports:
+     - Orchestrator: 9000
+     - ComfyUI: 8188
+     - vLLM: 8000+
+
+  8. Storage:
+     - Models cache: /workspace/huggingface_cache (~401GB)
+     - ComfyUI models: /workspace/ComfyUI/models (symlinks to cache)
+     - Project: /workspace/ai
+
+  For detailed documentation, see:
+  - /workspace/ai/README.md
+  - /workspace/ai/CLAUDE.md
+  - /workspace/ai/COMFYUI_MODELS.md
+  - /workspace/ai/MODELS_LINKED.md