Add step-by-step deployment guide

SETUP_FOR_DUMMIES.md

@@ -0,0 +1,172 @@
+# Ollama Qwen on Hugging Face Space (For Dummies)
+
+This is the exact workflow that worked.
+
+## 0) What you are building
+
+A Hugging Face **Docker Space** that:
+- starts `ollama`
+- pulls model `qwen2.5:0.5b`
+- serves a simple web app on port `7860`
+- exposes an API endpoint: `POST /api/chat`
+
+---
+
+## 1) One-time setup on your Mac
+
+### 1.1 Install Hugging Face CLI
+
+```bash
+curl -LsSf https://hf.co/cli/install.sh | bash
+```
+
+### 1.2 Login with token
+
+Create token at: https://huggingface.co/settings/tokens
+
+Token needs **write access** to your Space repo.
+
+```bash
+hf auth login
+```
+
+Optional check:
+
+```bash
+hf auth whoami
+```
+
+---
+
+## 2) Clone your Space repo
+
+```bash
+cd /Users/stelios/Desktop
+git clone https://huggingface.co/spaces/steliosot/llm
+cd llm
+```
+
+---
+
+## 3) Use the working files
+
+Copy the final known-good files:
+
+```bash
+cp /Users/stelios/Desktop/hf/{Dockerfile,app.py,start.sh,requirements.txt,README.md} /Users/stelios/Desktop/llm/
+```
+
+Quick check:
+
+```bash
+ls -la /Users/stelios/Desktop/llm
+```
+
+---
+
+## 4) Commit + push
+
+```bash
+cd /Users/stelios/Desktop/llm
+git add Dockerfile app.py start.sh requirements.txt README.md
+git commit -m "Deploy Ollama Qwen working setup"
+```
+
+If git says remote is ahead:
+
+```bash
+git pull --rebase origin main
+```
+
+Then push:
+
+```bash
+git push origin main
+```
+
+---
+
+## 5) Wait for Space build
+
+- Open your Space page
+- Wait for build + startup logs
+- First run pulls model (`~397 MB`) and can take a few minutes
+
+Expected good log signs:
+- `Listening on 127.0.0.1:11434`
+- `Pulling model qwen2.5:0.5b...`
+- `success`
+- `Uvicorn running on http://0.0.0.0:7860`
+
+---
+
+## 6) Test with curl (important)
+
+Your app is **FastAPI**, not Gradio.
+Use:
+
+```bash
+curl -sS -X POST "https://steliosot-llm.hf.space/api/chat" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt":"say hi"}'
+```
+
+If Space is private, add auth header:
+
+```bash
+curl -sS -X POST "https://steliosot-llm.hf.space/api/chat" \
+  -H "Authorization: Bearer hf_YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt":"say hi"}'
+```
+
+If you enabled app key (`APP_KEY`):
+
+```bash
+curl -sS -X POST "https://steliosot-llm.hf.space/api/chat" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt":"say hi","key":"my-secret"}'
+```
+
+---
+
+## 7) Common errors and fixes
+
+### Error: `This version requires zstd`
+Fix: ensure Dockerfile apt install includes `zstd`.
+
+### Error: `ImportError: cannot import name 'HfFolder'`
+Cause: Gradio + huggingface_hub mismatch.
+Fix used: moved to FastAPI app.
+
+### Error: `POST /run/predict 404`
+Expected now. That is a Gradio endpoint.
+Use `POST /api/chat` instead.
+
+### Error: `You are not authorized to push to this repo`
+Token is valid but not allowed for this repo.
+Create/use a token with **explicit write access** to `spaces/steliosot/llm`.
+
+### Error: `git push ... fetch first`
+Run:
+
+```bash
+git pull --rebase origin main
+git push origin main
+```
+
+---
+
+## 8) Final checklist
+
+- [ ] `hf auth whoami` works
+- [ ] files copied to `/Users/stelios/Desktop/llm`
+- [ ] `git push origin main` succeeds
+- [ ] Space logs show Uvicorn on port `7860`
+- [ ] curl to `/api/chat` returns a response
+
+You are done when this command returns model text:
+
+```bash
+curl -sS -X POST "https://steliosot-llm.hf.space/api/chat" -H "Content-Type: application/json" -d '{"prompt":"say hi"}'
+```