ComfyUI

After the comfyui 2.0 version, an overlay feature was added to enable environment persistence, allowing users to rollback to a previous version in case the environment is corrupted during upgrades or when installing certain nodes.

Starting ComfyUI with Docker Compose

The following example is suitable for Jetson AGX Orin (AI Pod X3), using the catdogai/comfyui:2.0.3-agxorin container image to start ComfyUI directly. Please ensure Docker and Docker Compose are installed on the device.

Create a new directory and inside it, create a docker-compose.yml file, writing the following configuration:

services:
  app:
    image: catdogai/comfyui:2.0.3-agxorin
    privileged: true
    volumes:
      - /etc/timezone:/etc/timezone:ro
      - /run/jtop.sock:/run/jtop.sock
      - /sys/firmware/devicetree:/sys/firmware/devicetree:ro
      - /proc/device-tree:/proc/device-tree:ro
      - ./lzc-comfy-data:/lzc-comfy-data
    ports:
      - 8188:8188
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8188/api/system_stats"]
      interval: 5s
      timeout: 5s
      retries: 100
      start_period: 30s

Execute in the directory of docker-compose.yml:

docker compose up -d

After startup, access http://localhost:8188 via the device's built-in browser. If accessing from another computer on the local network, open http://算力舱IP:8188.

The models, input/output files, and runtime environment will be persisted in the lzc-comfy-data directory under the current working directory. Please preserve this directory. On first startup, the runtime environment needs to be prepared. You can check the startup logs and service status using the following commands:

docker compose logs -f app
docker compose ps

Overlay Runtime Usage

The container image starts ComfyUI via lzc-comfy-overlay run. It synchronizes the immutable code and venv from within the container image to the persistent runtime layer, then launches the service from that runtime layer:

• Container image code directory: /opt/ComfyUI
• Container image venv: /opt/venv
• Runtime code link: /opt/ComfyUI-user
• Runtime venv link: /opt/venv-user
• Default data root directory: /lzc-comfy-data
• Overlay status directory: /lzc-comfy-data/overlay

The system prioritizes OverlayFS and mounts:

/lzc-comfy-data/overlay/merged/app
/lzc-comfy-data/overlay/merged/venv

If the current container or data disk does not support OverlayFS, the script will automatically downgrade to a regular persistent rsync operation mode. The downgrade mode allows ComfyUI to start up, but does not provide snapshot and rollback capabilities.

The user data directory will be migrated and linked to:

/lzc-comfy-data/overlay/userdata/user
/lzc-comfy-data/overlay/userdata/output
/lzc-comfy-data/overlay/userdata/input
/lzc-comfy-data/overlay/userdata/models

These directories will not be covered by container image upgrades. lzc-comfyui.ignore should only exclude the root directory's /user/***, /output/***, /input/***, /models/***, /temp/***. Do not use unanchored rules like input/, models/, as this may accidentally exclude subdirectories with the same name in ComfyUI's source code.

Common commands:

# 准备 overlay 挂载和升级同步，不启动 ComfyUI
lzc-comfy-overlay boot

# 完整启动流程，镜像 CMD 默认使用这个命令
lzc-comfy-overlay run

# 查看数据根目录、当前镜像版本、挂载状态和待处理回滚
lzc-comfy-overlay status

# 手动创建快照
lzc-comfy-overlay snapshot --reason before-manager-update

# 查看快照列表
lzc-comfy-overlay list

# 标记回滚目标，重启 app 容器后生效
lzc-comfy-overlay rollback <snapshot-id>

# 清理过期自动快照
lzc-comfy-overlay cleanup

The upgrade process is controlled by lzc-version. The previously recorded container image version on the device end is at:

/lzc-comfy-data/overlay/control/last-image-version

When /opt/ComfyUI/lzc-version in the new container image does not match the recorded value, or when COMFYUI_FORCE_UPDATE=1 is set, ComfyUI and the venv are synchronized during startup. Before synchronization, a pre-image-upgrade-* snapshot is created. After the upgrade, the service must pass the http://localhost:8188/api/manager/version health check within 300 seconds. If it fails, the script automatically rolls back to the pre-upgrade snapshot and restarts.

Available environment variables:

• LZC_COMFY_DATA_DIR: Overrides the default data root directory /lzc-comfy-data.
• COMFYUI_FORCE_UPDATE=1: Forces re-synchronization of the runtime layer from the container image.
• COMFYUI_DISABLE_UPDATE=1: Skips image synchronization if both runtime layer and venv are already available.

Automatic snapshots include startup snapshots, daily snapshots, and pre-upgrade snapshots. Automatic snapshots retain at most the last 5; snapshots older than 7 days are cleaned up at cleanup. Manual snapshots are not automatically cleaned.

Q: What if ksampler does not support sm87 CUDA instructions?

A: This is because the segattention library has not been adapted to support sm87 instructions. Simply changing /opt/venv/lib/python3.12/site-packages/sageattention/core.py to match the sm89 logic will resolve it.

Add Proxy

Create a proxy in the /ssd/lzc-ai-agent/services/cloud.lazycat.aipod.comfyui directory of the AI Pod. compose.override.yml

services:
  app:
    environment:
      - https_proxy=http://代理ip:代理端口

Note: If the proxy IP is not set to 127.0.0.1, the address will be inaccessible within the container.