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)

```bash
# 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:

```bash
./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

```bash
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:

```yaml
# .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.