DEPLOY.md

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):

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