reverse-dictionary/DEPLOY.md

🚀 النشر على Streamlit Community Cloud (مجاني)

التطبيق ينشر برابط عام. الملفات الكبيرة (النماذج + الـ embeddings) تُخزَّن على Hugging Face Hub (لأن GitHub المجاني يسمح بـ 1GB فقط)، والكود على GitHub، والتقييمات في Supabase.

GitHub (الكود)  →  Streamlit Cloud (يشغّل التطبيق)
                         │
                         ├─ ينزّل النماذج/الـ embeddings من  Hugging Face Hub
                         └─ يحفظ التقييمات في  Supabase

---

1) رفع الملفات الكبيرة إلى Hugging Face Hub

1. أنشئي حساب على https://huggingface.co (مجاني).
2. أنشئي Access Token: الصورة الشخصية → Settings → Access Tokens → New token (نوع Write). انسخيه.
3. في الطرفية (من مجلد reverse-dictionary/backend):

   export HF_TOKEN=hf_xxxxxxxx                       # التوكن من الخطوة 2
   export HF_DATA_REPO="USERNAME/reverse-dictionary-assets"   # بدّلي USERNAME
   .venv/bin/python scripts/upload_assets.py
   

4. بعد الرفع: افتحي المستودع على HF → Settings → اجعليه Public.

هذا يرفع ~1.7GB مرة واحدة. المستودع العام لا يحتاج توكن عند التنزيل.

---

2) إعداد قاعدة التقييمات (DATABASE_URL)

أنشئي قاعدة على SQLite Cloud https://sqlitecloud.io واحصلي على رابط الاتصال (يبدأ بـ sqlitecloud://...?apikey=...). الجداول تُنشأ تلقائيًا. (يدعم الكود أيضًا Supabase عبر رابط postgresql://.)

---

3) رفع الكود على GitHub

من جذر المشروع (semantic-search-system):

git add -A
git commit -m "تجهيز للنشر على Streamlit Cloud"
git branch -M main
git remote add origin https://github.com/USERNAME/REPO.git   # بدّلي
git push -u origin main

الملفات الكبيرة مُستثناة من Git (في .gitignore) — لا تُرفع على GitHub.

---

4) النشر على Streamlit Cloud

1. ادخلي https://share.streamlit.io وسجّلي دخول بحساب GitHub.
2. Create app → Deploy a public app from GitHub.
3. عبّئي:
   • Repository: مستودعك على GitHub.
   • Branch: main.
   • Main file path: reverse-dictionary/frontend/streamlit_app.py
   • Advanced settings → Python version: 3.11
4. في Advanced settings → Secrets، الصقي:

   HF_DATA_REPO = "USERNAME/reverse-dictionary-assets"
   DATABASE_URL = "postgresql://postgres.xxxx:PASSWORD@...pooler.supabase.com:6543/postgres"
   

5. Deploy!

أول تشغيل بطيء: يثبّت المكتبات ثم ينزّل ~1.7GB من HF Hub. الإقلاعات اللاحقة أسرع.

---

5) متابعة التقييمات

من لوحة Supabase → Table Editor → ratings تشوفين كل التقييمات وتصدّرينها CSV.

---

⚠️ ملاحظات

• الذاكرة: Streamlit Cloud المجاني محدود الذاكرة. خفّفنا الاستهلاك (نماذج مُكمَّمة + mmap للـ embeddings). لو ظهر خطأ ذاكرة (الرسالة "Oh no"/إعادة تشغيل متكررة)، الحل الأأمن هو Hugging Face Spaces (ذاكرته 16GB) بنفس هذي الملفات.
• عند تحديث الكود: ادفعي على GitHub، و Streamlit Cloud يعيد النشر تلقائيًا.
• عند تحديث النماذج/الـ embeddings: أعيدي تشغيل upload_assets.py، ثم أعيدي تشغيل التطبيق من لوحة Streamlit Cloud (Reboot) لإعادة التنزيل.