DEPLOYMENT_GUIDE.md

🚀 دليل النشر - محول DOCX إلى PDF للعربية

📋 خيارات النشر

1. 🌐 Hugging Face Spaces (الموصى به)

الخطوات:

1. إنشاء Space جديد:

   • اذهب إلى Hugging Face Spaces
   • اضغط "Create new Space"
   • اختر "Gradio" كـ SDK
   • اختر اسم للـ Space

2. رفع الملفات:

   git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
   cd YOUR_SPACE_NAME
   
   # نسخ الملفات المطلوبة
   cp /path/to/your/project/app.py .
   cp /path/to/your/project/requirements.txt .
   cp /path/to/your/project/packages.txt .
   cp /path/to/your/project/README.md .
   
   # رفع التغييرات
   git add .
   git commit -m "Add Arabic DOCX to PDF converter"
   git push
   

3. التحقق من النشر:

   • انتظر بناء الـ Space (5-10 دقائق)
   • تحقق من السجلات للتأكد من تثبيت الخطوط العربية
   • اختبر التحويل بملف عربي بسيط

المزايا:

• ✅ مجاني ومتاح 24/7
• ✅ تثبيت تلقائي للتبعيات
• ✅ واجهة ويب جاهزة
• ✅ مشاركة سهلة عبر الرابط

2. 🐳 Docker (للتشغيل المحلي)

الخطوات:

# بناء الصورة
docker build -t docx-pdf-arabic .

# تشغيل الحاوية
docker run -p 7860:7860 docx-pdf-arabic

# أو استخدام docker-compose
docker-compose up -d

المزايا:

• ✅ بيئة معزولة ومستقرة
• ✅ سهولة النشر على خوادم مختلفة
• ✅ تحكم كامل في البيئة

3. 🖥️ التشغيل المحلي المباشر

الخطوات:

# تثبيت التبعيات النظام (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install libreoffice libreoffice-writer \
  fonts-liberation fonts-dejavu fonts-noto fontconfig

# تثبيت التبعيات Python
pip install -r requirements.txt

# تشغيل التطبيق
python run_local.py

المزايا:

• ✅ أداء أسرع
• ✅ تحكم كامل في النظام
• ✅ سهولة التطوير والاختبار

🔧 إعدادات التحسين

لـ Hugging Face Spaces:

1. تحسين packages.txt:

   libreoffice
   libreoffice-writer
   libreoffice-l10n-ar
   fonts-noto-naskh
   fonts-amiri
   fontconfig
   

2. تحسين requirements.txt:

   gradio==4.20.0
   

3. إعدادات README.md:

   • تأكد من وجود YAML frontmatter صحيح
   • اضبط sdk_version على النسخة الصحيحة

للخوادم المخصصة:

1. تحسين الذاكرة:

   export JAVA_OPTS="-Xmx2g"
   export SAL_DISABLE_OPENCL=1
   

2. تحسين الخطوط:

   fc-cache -fv
   fc-list | grep -i arabic
   

🧪 اختبار النشر

1. اختبار أساسي:

python test_conversion.py

2. اختبار الخطوط العربية:

fc-list | grep -i "amiri\|noto.*arabic"

3. اختبار LibreOffice:

libreoffice --headless --convert-to pdf test.docx

🔍 استكشاف أخطاء النشر

مشكلة: LibreOffice لا يعمل

الحل:

# تحقق من التثبيت
libreoffice --version

# إعادة تثبيت
sudo apt-get remove --purge libreoffice*
sudo apt-get install libreoffice libreoffice-writer

مشكلة: الخطوط العربية مفقودة

الحل:

# تثبيت خطوط إضافية
sudo apt-get install fonts-noto-naskh fonts-amiri

# تحديث cache
sudo fc-cache -fv

# التحقق
fc-list | grep -i arabic

مشكلة: أخطاء الذاكرة

الحل:

# زيادة حد الذاكرة
export JAVA_OPTS="-Xmx4g"

# تعطيل OpenCL
export SAL_DISABLE_OPENCL=1

مشكلة: بطء التحويل

الحل:

• قلل حجم الملفات المدخلة
• استخدم خادم بمواصفات أعلى
• فعل التخزين المؤقت

📊 مراقبة الأداء

مؤشرات مهمة:

• وقت التحويل (يجب أن يكون < 30 ثانية للملفات العادية)
• استخدام الذاكرة (يجب أن يكون < 2GB)
• معدل نجاح التحويل (يجب أن يكون > 95%)

أدوات المراقبة:

# مراقبة الذاكرة
htop

# مراقبة العمليات
ps aux | grep libreoffice

# مراقبة السجلات
tail -f /var/log/syslog

🔒 الأمان

إعدادات الأمان:

1. تحديد حجم الملفات المرفوعة (< 50MB)
2. تنظيف الملفات المؤقتة تلقائياً
3. تحديد وقت انتهاء للعمليات (timeout)
4. منع تنفيذ الكود الضار في الملفات

أفضل الممارسات:

• استخدم HTTPS دائماً
• فعل rate limiting
• راقب استخدام الموارد
• احتفظ بنسخ احتياطية من الإعدادات

📞 الدعم

إذا واجهت مشاكل في النشر:

1. تحقق من السجلات أولاً
2. تأكد من تثبيت جميع التبعيات
3. اختبر على بيئة محلية أولاً
4. راجع دليل استكشاف الأخطاء أعلاه