إعداد بيئة التطوير (محليًا)

أعدّ بيئة التطوير الخاصة بك على خادمك المحلي أو حاسوبك المكتبي.

​

المتطلبات المسبقة

يُعد Overleaf مشروعًا نموذجيًا مفتوح المصدر قائمًا على بنية الخدمات المصغّرة (microservices)، حيث تعمل جميع الخدمات داخل Docker.

• الشيفرة المصدرية الرسمية لإصدار Community Edition موجودة على GitHub Overleaf Official.
• الشيفرة المصدرية لـ Overleaf-CEP متاحة على GitHub Yu-i-i/Overleaf.
• إصدار Overleaf Pro متاح على GitHub Ayaka-notes/overleaf-pro.

لإعداد بيئة تطوير Overleaf، ستحتاج إلى خادم قوي؛ يُوصى بتكوين لا يقل عن 8 أنوية و16 جيجابايت من ذاكرة RAM، لأنك ستحتاج إلى تشغيل أكثر من 20 حاوية في الوقت نفسه.

نظرًا لأن الخوادم التي تحتوي على 8 أنوية معالج أو أكثر تكون عادةً باهظة الثمن، يُوصى بشدة باستخدام حاسوبك المحلي للتطوير.

في الوقت نفسه، وبصفتك مطورًا، نعتقد أنك على دراية مسبقة بـ تثبيت Docker. ننصح بشدة باستخدام إصدار حديث ومستقر من Ubuntu LTS (مثل Ubuntu 24.04 في 2025–2026) وأحدث إصدار من Docker للتطوير، لأن ذلك يقلل من احتمال مواجهة أخطاء غير متوقعة.

باختصار، ستحتاج إلى:

• خادم أو حاسوب مكتبي قوي للتطوير
• إصدار حديث ومستقر من Ubuntu LTS (مثل Ubuntu 24.04)
• بيئة Docker وGit

​

دليل الإعداد

سنستخدم هنا overleaf-cep كمثال لتوضيح كيفية إعداد بيئة تطوير Overleaf.

1. سحب الشيفرة المصدرية

   أولًا، لنقم باستنساخ المستودع:

   bash

   git clone https://github.com/ayaka-notes/overleaf-pro.git
   cd overleaf-pro
   
2. مزامنة package-lock.json

   نظرًا لأن Overleaf يُطوَّر في مستودع داخلي، فمن المرجح جدًا أن يصبح ملف package-lock.json غير متزامن بسبب بعض مشكلات التطوير. نحتاج إلى تشغيل الأمر التالي لمزامنته (إذا كانت لديك بيئة nodejs محلية):

   bash

   npm install --package-lock-only --ignore-scripts
   

   إذا لم يكن nodejs مثبتًا لديك، فلا تقلق، يمكنك استخدام docker مباشرةً لتشغيل الأمر نفسه. شغّله من جذر مستودع Overleaf:

   bash

   docker run --rm \
     -v "$(pwd)":/workspace \
     -w /workspace \
     node:22.18.0 \
     npm install --package-lock-only --ignore-scripts
   
3. بناء صورة التطوير

   يوفر Overleaf مجلدًا مخصصًا /develop لتخزين سكربتات التطوير. ما عليك سوى بناء الخدمات:

   bash

   cd ./develop
   bin/build
   

   إذا نفدت ذاكرة RAM لدى Docker أثناء بناء الخدمات بالتوازي، فأنشئ ملف .env في هذا المجلد يحتوي على COMPOSE_PARALLEL_LIMIT=1.

4. تشغيل جميع الخدمات المصغّرة

   ثم شغّل الخدمات:

   bash

   bin/up
   

   بمجرد تشغيل الخدمات، افتح http://localhost/launchpad لإنشاء أول حساب مسؤول.

   يجب تشغيل bin/up قبل تشغيل الأمر bin/dev. وإلا فقد تواجه سلسلة من مشكلات الأذونات.

افتراضيًا، لا تكون صلاحيات المسؤول متاحة. تحتاج إلى إضافة ما يلي إلى develop/dev.env. بعد ذلك، يمكنك الوصول إلى لوحة الإدارة.

ADMIN_PRIVILEGE_AVAILABLE=true

​

TeX Live

يتطلب إنشاء ملف PDF بناء صورة TeX Live لمعالجة الترجمة داخل Docker:

docker build texlive -t texlive-full

للترجمة على مضيف macOS، قد تحتاج إلى تجاوز مسار مقبس Docker عن طريق إنشاء ملف .env في هذا المجلد يحتوي على DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

يمكنك أيضًا استخدام ayaka-notes/texlive-full، ويمكنك استخدام الوسم base، وهو الإصدار الأدنى من texlive.

​

التطوير

لتجنب تشغيل bin/build && bin/up بعد كل تغيير في الشيفرة، يمكنك تشغيل Overleaf Community Edition في وضع التطوير، حيث تُحدَّث الخدمات تلقائيًا عند تغيير الشيفرة.

للقيام بذلك، استخدم السكربت المضمّن bin/dev:

bin/dev

سيؤدي ذلك إلى تشغيل جميع الخدمات باستخدام node --watch، الذي يراقب الشيفرة تلقائيًا ويعيد تشغيل الخدمات عند الحاجة.

لتحسين الأداء، يمكنك تشغيل مجموعة فرعية فقط من الخدمات في وضع التطوير عن طريق تمرير قائمة مفصولة بمسافات إلى السكربت bin/dev:

bin/dev [service1] [service2] ... [serviceN]

سيؤدي تشغيل خدمة web في وضع التطوير إلى تحديث خدمة web فقط عند تغيير شيفرة الواجهة الخلفية. ولتحديث شيفرة الواجهة الأمامية تلقائيًا أيضًا، تأكد من تشغيل خدمة webpack في وضع التطوير كذلك.

إذا لم تُحدَّد أي خدمات، فستعمل جميع الخدمات في وضع التطوير.

​

تصحيح الأخطاء

عند التشغيل في وضع التطوير، تكشف معظم الخدمات منفذًا لتصحيح الأخطاء يمكنك ربط مصحح أخطاء به، مثل أداة الفحص في Chrome Dev Tools أو مصحح مدمج في بيئة تطوير متكاملة (IDE). يوضح الجدول التالي المنفذ المكشوف على الجهاز المضيف لكل خدمة:

الخدمة	المنفذ
web	9229
clsi	9230
chat	9231
contacts	9232
docstore	9233
document-updater	9234
filestore	9235
notifications	9236
real-time	9237
references	9238
history-v1	9239
project-history	9240
linked-url-proxy	9241

للاتصال بخدمة باستخدام التصحيح عن بُعد في Chrome، انتقل إلى chrome://inspect/ وتأكد من تحديد Discover network targets. ثم انقر على Configure… وأضف إدخالًا localhost:[service port] لكل خدمة تريد ربط مصحح الأخطاء بها.

بعد إضافة الإدخال، ستظهر الخدمة كـ Remote Target يمكنك فحصها وتصحيح أخطائها.

​

السجلات

في بيئة التطوير، يوفر overleaf السكربت bin/logs، لكنك تحتاج إلى تثبيت بعض الاعتماديات:

sudo npm install -g bunyan
# Or sudo apt install node-bunyan 

أو يمكنك التشغيل مباشرةً باستخدام:

docker compose logs -f [service name]

​

أدوات أخرى

بعد الانتهاء من كل ما سبق، يمكنك الرجوع إلى القسم التالي لإضافة بعض أدوات تصحيح الأخطاء إلى بيئة تطوير overleaf الخاصة بك.