DEPLOY_TO_SPACES.md

Deploying this project to Hugging Face Spaces

This document explains three ways to deploy the contents of this repository to a Hugging Face Space:

• Option A — Static Space (recommended for a plain website: fastest to set up)
• Option B — Gradio Space (if you want a Python-backed UI wired into models)
• Option C — Docker / "Other" Space (if you need to run server.py with FastAPI / Uvicorn)

All commands below assume PowerShell on Windows (your environment). If you use the workspace virtualenv, run the CLI commands from that environment or prepend the correct python -m calls.

Preparation

1. Create a Hugging Face account if you do not already have one: https://huggingface.co/
2. Install Hugging Face Hub CLI locally (recommended inside your venv):

&pip install --upgrade huggingface_hub
# then login interactively
& huggingface-cli login

3. Choose a Space name (e.g. your-username/my-space).

Note: Hugging Face Spaces supports several Space types. Pick the one that fits your app:

• static — best for a static website (HTML/CSS/JS). No Python runtime needed.
• gradio or streamlit — for Python UIs using those frameworks.
• docker or other — you provide a Dockerfile (useful for FastAPI or custom servers).

---

Option A — Static Space (recommended for index.html/frontend-only sites)

Use this option when your site is pure client-side HTML/CSS/JS. It is the simplest and fastest option.

1. Ensure the static site entrypoint is index.html at the repository root. Currently this repo contains static/index.html. You can either:

   • Move content from static/ to the repository root, or
   • Create a tiny wrapper index.html at repo root that loads ./static/index.html with an iframe or server-side redirect (but moving is simplest).

   Example to copy files (PowerShell):

# from repo root
Copy-Item -Path .\static\* -Destination . -Recurse -Force

2. Create the Space (replace <your-username> and <space-name>):

huggingface-cli repo create <your-username>/<space-name> --type=static

3. Initialize a git repo and push the site to the new Space remote:

git init
git add .
git commit -m "Deploy static site to HF Space"
# add remote; replace with the exact URL from the CLI output if different
git remote add origin https://huggingface.co/spaces/<your-username>/<space-name>
git branch -M main
git push -u origin main

4. Your Space will build and serve the static site. Visit https://huggingface.co/spaces//

Notes:

• If you have large assets (models, weights), store them in a separate repo or use Git LFS. Spaces have storage limits.
• Static Spaces do not provide a Python runtime.

---

Option B — Gradio Space (if you want a Python UI)

If you want to serve a simple Python UI that can interact with your models, use Gradio. This is great when you need Python code to run on the server side.

1. Create the Space as a Gradio type:

huggingface-cli repo create <your-username>/<space-name> --type=gradio

2. Add a minimal app.py (Gradio) in the repo root. Example that serves your existing static/index.html inside a Gradio interface:

import gradio as gr
from pathlib import Path

html = Path("static/index.html").read_text(encoding="utf-8")

def show():
    return html

iface = gr.Interface(fn=show, inputs=[], outputs=gr.HTML(), allow_flagging=False)

if __name__ == "__main__":
    iface.launch(server_name="0.0.0.0", server_port=7860)

3. Ensure requirements.txt includes gradio (add gradio>=3.0 if missing). Commit and push like in Option A.

4. Visit your Space URL after the build completes.

Notes:

• Gradio Spaces run in a Python environment and will install packages from requirements.txt.
• Models and large files may require Git LFS or external hosting.

---

Option C — Docker / "Other" Space (for FastAPI / custom servers)

Use this when you need to run server.py (FastAPI + Uvicorn) as the backend. This option gives you complete control via a Dockerfile.

1. Create the Space as a Docker/Other Space:

huggingface-cli repo create <your-username>/<space-name> --type=docker

2. Add a Dockerfile to the repo root. Example for running server.py with Uvicorn:

FROM python:3.11-slim
WORKDIR /app
COPY . /app
RUN pip install --upgrade pip && pip install -r requirements.txt
ENV PORT=7860
CMD ["bash", "-lc", "uvicorn server:app --host 0.0.0.0 --port $PORT"]

Make sure server.py exposes a FastAPI app object (for example app = FastAPI()), so uvicorn server:app works.

3. Commit and push the repo to the Space remote as in Option A. Spaces will build the Docker image and run it.

Notes:

• Docker images must fit within Spaces resource constraints. Avoid bundling large model weights in the image; prefer downloading at runtime or using external storage.
• Use $PORT env var as shown so the platform can route correctly.

---

Common tips

• If your index.html and assets live under static/, one simple approach is to move them to the repository root before pushing a Static Space.
• For debugging, check the Space build logs on the Space page — they show package install errors and startup logs.
• To upload large model files, use Git LFS or host the weights on the Hugging Face Hub (or external storage) and download them at runtime.

Example minimal PowerShell session (Static Space)

# login
huggingface-cli login
# create space
huggingface-cli repo create my-username/my-static-site --type=static
# copy files to repo root (if required)
Copy-Item -Path .\static\* -Destination . -Recurse -Force
# push
git init
git add .
git commit -m "Deploy static site to HF Space"
git remote add origin https://huggingface.co/spaces/my-username/my-static-site
git branch -M main
git push -u origin main

Follow-ups I can help with

• Create a Dockerfile in this repo to run server.py on Spaces (I can add it and test locally).
• Add a Gradio app.py wrapper so the current static/index.html is served inside a Gradio app.
• Move/copy static/ contents to the project root and configure a Static Space, then push for you (if you want me to modify repo files).

If you'd like, tell me which option you prefer (Static, Gradio, or Docker), and I will add the required files and example configuration in this repository.