دليل تثبيت كامل (Ubuntu Server → Frappe/Bench → omnexa_core)

هذا الدليل يشرح التثبيت من الصفر على سيرفر Ubuntu حتى تشغيل موقع (Site) مع omnexa_core.

ملاحظة مهمة: omnexa_core (على فرع develop) أصبح قادرًا على جلب التطبيقات المطلوبة تلقائيًا عبر bench get-app قبل التثبيت على الـ Site (إذا كانت مفقودة من الـ bench).

1) متطلبات السيرفر

• Ubuntu 24.04 LTS (موصى به) أو Ubuntu 22.04 LTS
• مستخدم Linux عادي (مثال: frappeuser) بصلاحية sudo
• اسم نطاق DNS (اختياري في البداية)
• فتح المنافذ: 22 (SSH) + 80/443 (Nginx) أو 8000 (dev)

2) تحديث النظام وتثبيت أدوات أساسية

sudo apt update && sudo apt -y upgrade
sudo apt -y install git curl wget vim software-properties-common ca-certificates

3) تثبيت المتطلبات (Python/Node/Yarn/Redis/MariaDB)

3.1 Python و أدوات البناء

sudo apt -y install python3-dev python3-pip python3-venv build-essential

3.2 MariaDB و Redis

sudo apt -y install mariadb-server mariadb-client redis-server
sudo systemctl enable --now mariadb redis-server

3.3 Node.js و Yarn

Frappe v15 يعمل عادةً بشكل ممتاز مع Node 18.

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt -y install nodejs
sudo npm install -g yarn

3.4 wkhtmltopdf (للطباعة PDF)

sudo apt -y install xvfb libfontconfig wkhtmltopdf

3.5 تهيئة MariaDB لإعدادات Frappe

sudo mysql_secure_installation

ثم أضف إعدادات UTF8MB4:

sudo tee /etc/mysql/mariadb.conf.d/99-frappe.cnf > /dev/null <<'EOF'
[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4
EOF

sudo systemctl restart mariadb

4) تثبيت bench و إنشاء bench جديد

4.1 تثبيت bench

sudo pip3 install frappe-bench

4.2 إنشاء bench

bench init frappe-bench --frappe-branch version-15
cd frappe-bench

لو عندك مشاكل صلاحيات/تشغيل: تأكد أن المستخدم الحالي هو الذي أنشأ الـ bench (مثال frappeuser).

5) إنشاء Site جديد

bench new-site erpgenex.local.site

5.1 (اختياري) تعيين الموقع الافتراضي

bench use erpgenex.local.site

6) تنزيل omnexa_core (من GitHub) وتثبيته

6.1 جلب التطبيق

bench get-app https://github.com/ErpGenex/omnexa_core.git --branch develop

6.2 تثبيت التطبيق على الـ Site

bench --site erpgenex.local.site install-app omnexa_core

6.3 الجلب التلقائي للتطبيقات المطلوبة (مهم)

خلال تثبيت omnexa_core، إذا كانت تطبيقات الـ stack المطلوبة غير موجودة داخل apps/، سيقوم omnexa_core بمحاولة:

• bench get-app ... --skip-assets لكل تطبيق مفقود
• ثم bench setup requirements
• ثم يُكمل التثبيت

يمكن التحكم بالميزة:

# تعطيل الجلب التلقائي
export OMNEXA_AUTO_GET_APPS=0

# تغيير المنظمة/الفرع (إن لزم)
export ERPGENEX_GITHUB_ORG=ErpGenex
export OMNEXA_APPS_BRANCH=develop

7) تشغيل النظام

7.1 تشغيل في وضع التطوير (سريع)

bench start

ثم افتح:

• http://<server-ip>:8000

7.2 تشغيل Production (مختصر)

تفاصيل production تعتمد على Nginx + Supervisor/Systemd. كخطوة أولى:

sudo bench setup production frappeuser

ثم:

• افتح http://<server-ip> عبر Nginx

8) استكشاف الأخطاء الشائعة

8.1 خطأ: No module named '<app>'

• يعني أن التطبيق غير موجود داخل apps/ أو لم يتم تثبيته داخل بيئة الـ bench.
• الحل:

bench get-app https://github.com/ErpGenex/<app>.git --branch develop
bench setup requirements

8.2 خطأ: MariaDB Access denied أثناء migrate/install

تأكد من:

• sudo systemctl status mariadb يعمل
• بيانات قاعدة البيانات داخل sites/<site>/site_config.json صحيحة

8.3 bench drop-site يطلب كلمة مرور root

مررها كـ option لتجنب التفاعل:

bench drop-site erpgenex.local.site --no-backup --force --root-login root --root-password 'YOUR_MYSQL_ROOT_PASSWORD'

9) تحقق سريع بعد التثبيت

bench --site erpgenex.local.site list-apps
bench --site erpgenex.local.site migrate
bench build