docs/DEPLOY_HF.md

Deploying MicroClimate-X to Hugging Face Spaces

一次部署，永久公网 URL，导师随时可看，不用挂笔记本。
One-time deploy → permanent public URL your supervisor can open any time, no laptop required.

---

Why Hugging Face Spaces?

• Free persistent hosting for ML demos (CPU tier is enough for this project).
• Docker SDK — reuses the existing Dockerfile 1:1, no platform-specific build hacks.
• Server-side Git LFS — the 217 MB rf_model.pkl uploads through huggingface-cli without needing local git-lfs installed.
• The HF Space URL (https://huggingface.co/spaces/<user>/microclimate-x) is the canonical demo URL for ML thesis projects in 2026.

---

Architecture on HF Spaces

┌──────────────────────────────────────────────────────────────┐
│  https://huggingface.co/spaces/<user>/microclimate-x         │
│                                                              │
│  Docker image (this repo's Dockerfile)                       │
│   ├─ FastAPI @ :8000   (declared via README.md `app_port`)   │
│   ├─ /app/frontend/  ── mounted at /app/                     │
│   ├─ /app/models/    ── rf_model.pkl baked in                │
│   └─ /tmp/cache.sqlite3 (ephemeral — fine for demo)          │
│                                                              │
│  ↓ outbound HTTP                                             │
│  ├─ api.open-meteo.com           (weather, ERA5)             │
│  └─ api.opentopodata.org/srtm30m (DEM)                       │
└──────────────────────────────────────────────────────────────┘

The frontend talks to its own origin via relative /api/… URLs, so no CORS fiddling and no front-end edits are needed.

---

3-step deploy

Step 1 — Create the Space (web UI, one minute)

1. Go to https://huggingface.co/new-space
2. Fill in:
   • Owner: your HF account
   • Space name: microclimate-x
   • License: MIT
   • Space SDK: Docker → "Blank" template
   • Hardware: CPU basic (free)
   • Visibility: Public
3. Click Create Space. You'll land on an empty repo page.

Step 2 — Authenticate the CLI (one minute)

# Install once
pip install -U "huggingface_hub[cli]"

# Get a token at https://huggingface.co/settings/tokens
#   - Type: Write
#   - Scope: read + write to the new Space
huggingface-cli login
# (paste the token when prompted)

Step 3 — Push (one command)

From the repo root:

./scripts/deploy_hf.sh <hf-username>/microclimate-x
# e.g.
./scripts/deploy_hf.sh KyoukoLi/microclimate-x

The script uploads:

• backend/, frontend/, scripts/, models/, docs/
• Dockerfile, requirements.txt, README.md, LICENSE, pyproject.toml

and skips local-only junk (data/, figures/, tests/, .venv/, SQLite caches, …).

HF then runs the same Dockerfile you use locally. Build takes ≈ 3–5 min the first time (the 217 MB model upload dominates) and < 1 min for subsequent deploys.

When the Space's status badge turns green ("Running"), the URL https://huggingface.co/spaces/<user>/microclimate-x is live. Send that to your supervisor.

---

Updating the demo after code changes

git commit -am "fix: …"
./scripts/deploy_hf.sh KyoukoLi/microclimate-x

The script diffs against the remote, so only changed files are re-uploaded. A code-only change (no model retrain) is a < 10 s push.

---

Troubleshooting

Symptom	Likely cause	Fix
Build log: unable to open database file	MICROCLIMATEX_DB points to a read-only path on HF	Dockerfile already sets it to /tmp/cache.sqlite3. Make sure your Space doesn't override it under Settings → Variables and secrets.
Build log: port 7860 expected, got 8000	HF didn't parse the app_port frontmatter	Confirm README.md starts with the YAML block including app_port: 8000.
App loads but every request → 502	Outbound calls to Open-Meteo / Open Topo Data hit HF's egress timeout	Increase httpx.AsyncClient(timeout=…) in backend/main.py (currently 15 s).
ML predictor banner says "heuristic"	models/rf_model.pkl wasn't uploaded	Re-run ./scripts/deploy_hf.sh; the script prompts before continuing without the model.
LFS quota exceeded	Free HF accounts get 5 GB LFS — we use ~220 MB	Delete old commits' LFS objects under Files & versions → Settings.

---

Optional: GitHub Actions auto-sync

If you'd rather have git push origin main auto-deploy to HF, add this workflow:

# .github/workflows/sync-to-hf.yml
name: Sync to Hugging Face Space
on:
  push:
    branches: [main]
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install -U "huggingface_hub[cli]"
      - run: |
          echo "${{ secrets.HF_TOKEN }}" | huggingface-cli login --token "$(cat -)"
          ./scripts/deploy_hf.sh KyoukoLi/microclimate-x

Add HF_TOKEN to the GitHub repo's secrets. Now every push to main re-deploys the Space.