docs/HUGGINGFACE_SPACE.md

Hugging Face Space Deployment

This deployment path runs SumakaClone as a Docker Space on Hugging Face.

What Runs Inside the Space

• FastAPI API and admin dashboard
• Telegram bot polling worker
• Celery worker
• Celery beat scheduler
• Local Redis for queueing

What Stays External

• Remote ComfyUI backend

MongoDB and Redis run inside the Space container by default. The only required external runtime service is the remote ComfyUI backend.

Required Space Secrets

Set these in the Space Settings:

• BOT__TOKEN
• SECURITY__JWT_SECRET
• COMFYUI__BASE_URL
• COMFYUI__WEBSOCKET_URL

Recommended:

• BOT__USERNAME
• BOT__ADMIN_IDS
• MONGO__DATABASE
• HUGGINGFACE__TOKEN

Optional:

• STORAGE__PROVIDER=r2 and the related R2 credentials if you want persistent generated images outside the Space.

If you stay on local storage, the Space will serve files from /storage, but those files are only durable if you attach a persistent volume or storage bucket.

Runtime Defaults

The Hugging Face Space Dockerfile already sets:

• API__PORT=7860
• MONGO__URI=mongodb://127.0.0.1:27017
• local Redis URLs for app and Celery
• STORAGE__PROVIDER=local
• STORAGE__LOCAL_ROOT=/data/storage
• FEATURES__ENABLE_PAYMENTS=false
• FEATURES__ENABLE_MODEL_AUTO_SYNC=false

If the Space exposes SPACE_HOST, the app automatically derives:

• API__PUBLIC_BASE_URL=https://$SPACE_HOST
• STORAGE__PUBLIC_BASE_URL=https://$SPACE_HOST/storage

Deploy Steps

1. Create a new Hugging Face Space using the Docker SDK.
2. Push this repository to that Space.
3. Add the required secrets in the Space Settings.
4. Keep your remote ComfyUI notebook running and paste its latest tunnel URL into:
   • COMFYUI__BASE_URL
   • COMFYUI__WEBSOCKET_URL
5. After the Space builds, open:
   • /admin
   • /docs

Notes

• Free CPU Spaces may sleep when unused, so the Telegram bot may not stay continuously online on free hardware.
• The Space exposes one public port, but internal services like Redis can still run on internal ports in the same container.
• Local MongoDB, Redis, and image storage are ephemeral unless you attach persistent storage.
• If the Colab or Kaggle ComfyUI tunnel changes, update the two ComfyUI secrets and restart the Space.