# Deploy Guide — Run 24/7 with full CryptoBERT (free)

This guide is written for someone who has **never deployed before**. Follow it
top to bottom. Two free services do the work:

- **Hugging Face Spaces** = runs your app 24/7 (dashboard + admin + full ML). 16GB RAM, free.
- **GitHub Actions** = a free scheduler that fires your 2×/day emails and keeps the Space awake.

You already have the code on GitHub. Total time: ~20 minutes.

---

## Part A — Put the app on Hugging Face Spaces

### A1. Make an account
1. Go to **https://huggingface.co/join** and sign up (free, no card).
2. Verify your email.

### A2. Create a Space
1. Click your avatar (top-right) → **New Space**.
2. Fill in:
   - **Owner**: your username
   - **Space name**: `crypto-narrative-terminal`
   - **License**: MIT
   - **Select the SDK**: choose **Docker** → **Blank**
   - **Hardware**: `CPU basic · 16GB · free`
   - **Visibility**: Private (only you) or Public — your choice
3. Click **Create Space**. You now have an empty Space with its own git address like:
   `https://huggingface.co/spaces/YOUR_NAME/crypto-narrative-terminal`

### A3. Push your code into the Space
A Space is its own git repo. From your project folder (`C:\dev\News-Narrative-Analysis`):

```bash
# 1) Log in to Hugging Face from your machine (one time)
pip install huggingface_hub
huggingface-cli login          # paste a token from huggingface.co/settings/tokens (role: write)

# 2) Add the Space as a second git remote (replace YOUR_NAME)
git remote add space https://huggingface.co/spaces/YOUR_NAME/crypto-narrative-terminal

# 3) Push your code to it
git push space main
```

> If `git push space main` complains about the remote having a README, run
> `git pull space main --allow-unrelated-histories` first, then push again.

That's it — Hugging Face sees the `Dockerfile` and starts **building automatically**.
The first build takes ~10–15 min (it downloads CryptoBERT). Watch the **Logs** tab.

### A4. Add your secrets (environment variables)
In the Space: **Settings** → **Variables and secrets** → **New secret**. Add each:

| Name | Value |
|------|-------|
| `ADMIN_PASSWORD` | a strong password you choose |
| `CRON_SECRET` | a long random string (e.g. mash your keyboard 30+ chars) |
| `NEWSDATA_API_KEY` | your NewsData key |
| `SMTP_HOST` | `smtp.gmail.com` |
| `SMTP_PORT` | `587` |
| `SMTP_USER` | your gmail address |
| `SMTP_PASS` | your 16-char Gmail App Password |
| `SMTP_FROM` | `Crypto Narrative <youremail@gmail.com>` |

After adding secrets, click **Settings → Factory rebuild** (or **Restart**) so they load.

### A5. Open your live app
Top of the Space → the app appears in the embedded window, and the direct URL is:
`https://YOUR_NAME-crypto-narrative-terminal.hf.space`

That URL is what you share with clients. The admin panel is at `…hf.space/admin`.

---

## Part B — Reliable 2×/day emails (GitHub Actions)

The workflow file is already in your repo at `.github/workflows/brief-cron.yml`.
You just give it two secrets.

1. Go to your GitHub repo → **Settings** → **Secrets and variables** → **Actions**.
2. Click **New repository secret** twice:

| Name | Value |
|------|-------|
| `APP_URL` | `https://YOUR_NAME-crypto-narrative-terminal.hf.space` (no trailing slash) |
| `CRON_SECRET` | the **same** random string you put in the Space |

3. Go to the **Actions** tab → if prompted, click **"I understand, enable workflows"**.
4. Test it: Actions → **Email Brief Cron** → **Run workflow** → check it turns green.

What it does automatically:
- **09:00 & 21:00 UTC** → sends the brief to your active clients
- **every 30 min** → pings the Space so it never falls asleep

> Want different send times? Edit the `cron:` lines in `.github/workflows/brief-cron.yml`
> (times are UTC) and also the matching hours in the "Decide action" step.

---

## Part C — Add your clients

1. Open `https://YOUR_NAME-crypto-narrative-terminal.hf.space/admin`
2. Log in with your `ADMIN_PASSWORD`.
3. Add client emails, set the two send times, toggle **Auto-send ENABLED**, **Save**.
4. Click **Send Test Now** to confirm an email actually arrives.

---

## Testing checklist

- [ ] Space build finished (green "Running") and the dashboard loads
- [ ] `…hf.space/admin` login works
- [ ] **Send Test Now** delivers an email to yourself
- [ ] GitHub Actions **Run workflow** shows green
- [ ] Sentiment shows `engine: ensemble` (CryptoBERT live) after first refresh

---

## Troubleshooting

| Problem | Fix |
|---|---|
| Build fails on memory | You're on the wrong hardware — pick **CPU basic 16GB (free)** in Space Settings |
| `uvicorn: command not found` | You're not using the Dockerfile — make sure SDK is **Docker** |
| Emails don't send | Check SMTP secrets; Gmail needs an **App Password**, not your login password |
| Cron does nothing | Confirm `APP_URL` has no trailing slash and `CRON_SECRET` matches both places |
| Sentiment stuck on VADER | Model still downloading on first run; refresh after a few minutes |

---

## Important note on data persistence (free tier)

Hugging Face **free** Spaces use **temporary storage** — your SQLite history
(`narrative_analysis.db`) is wiped if the Space is rebuilt or factory-reset
(normal sleeps usually keep it, rebuilds don't). The dashboard always works,
but the **24h-trend and accuracy scorecard need continuous history** to mature.

Two ways to keep history permanently:
1. **HF persistent storage** — Space Settings → add persistent storage (small monthly fee), then set `DB_PATH=/data/narrative_analysis.db`.
2. **Free external database** — ask me to wire a free Postgres (Supabase/Neon); the DB then lives outside the Space and survives everything.

For now the app runs fully; history simply restarts on a rebuild. Tell me if you
want the permanent-storage option and I'll set it up.