المتطلبات المسبقة
يُعد Overleaf مشروعًا نموذجيًا مفتوح المصدر قائمًا على بنية الخدمات المصغّرة (microservices)، حيث تعمل جميع الخدمات داخل Docker.- الشيفرة المصدرية الرسمية لإصدار Community Edition موجودة على GitHub Overleaf Official.
- الشيفرة المصدرية لـ Overleaf-CEP متاحة على GitHub Yu-i-i/Overleaf.
- يتوفر Ayakaleaf Pro على GitHub ayaka-notes/ayakaleaf-pro.
نظرًا لأن الخوادم التي تحتوي على 8 أنوية معالج أو أكثر تكون عادةً باهظة الثمن، يُوصى بشدة باستخدام حاسوبك المحلي للتطوير.
- خادم أو حاسوب مكتبي قوي للتطوير
- إصدار حديث ومستقر من Ubuntu LTS (مثل Ubuntu 24.04)
- بيئة Docker وGit
دليل الإعداد
نستخدم هنا Ayakaleaf Pro لنوضح كيفية إعداد بيئة تطوير Overleaf. تُشغَّل جميع الأوامر أدناه في المجلدdevelop ما لم يُذكر خلاف ذلك.
1
سحب الشيفرة المصدرية
أولًا، لنقم باستنساخ المستودع:
bash
2
مزامنة yarn.lock
يستخدم المستودع Yarn 4 (يشغّل
packageManager في ملف package.json الجذري)، وقد يكون ملف yarn.lock غير متزامن مع ملفات package.json. زامنه بعد الاستنساخ الأول وبعد أي تغيير في package.json:bash
bin/sync الأمر yarn install --mode=update-lockfile داخل حاوية node:24.18.1، لذا لا تحتاج إلى Node.js على المضيف. لا تلتزم بملف yarn.lock المعدَّل.3
بناء صورة التطوير
ابنِ الخدمات:
bash
إذا نفدت ذاكرة RAM لدى Docker أثناء بناء الخدمات بالتوازي، فأنشئ ملف
.env في هذا المجلد يحتوي على COMPOSE_PARALLEL_LIMIT=1.4
تطبيق الترجمات
تحتفظ وحدات Ayakaleaf Pro بترجماتها في يحتاج إلى
services/web/locales/locales_patches/، وهي غير موجودة في ملفات اللغات الملتزَم بها. طبّقها مرة واحدة قبل التشغيل الأول، وإلا فستعرض صفحات هذه الوحدات مفاتيح مثل about_to_permanently_delete_accounts بدلًا من النص:bash
jq على المضيف. شغّله مجددًا بعد إضافة ترجمة أو تغيير الفرع، راجع تحديث ترجمات i18n.5
تشغيل جميع الخدمات المصغّرة
ثم شغّل الخدمات:بمجرد تشغيل الخدمات، افتح http://localhost/launchpad لإنشاء أول حساب مسؤول. أضف المنفذ إذا غيّرت
bash
OVERLEAF_PORT (انظر أدناه).يكون LDAP مفعّلًا افتراضيًا (
LDAP_ENABLED=true في dev.rc). عندها يعرض launchpad نموذج مسؤول LDAP: يطلب بريدًا إلكترونيًا فقط، ثم يسجّل هذا المسؤول الدخول عبر LDAP، مثلًا باسم professor / professor (professor@planetexpress.com). المستخدمون التجريبيون مدرجون في develop/authentication/README.md. اضبط LDAP_ENABLED=false وSAML_ENABLED=false لإنشاء مسؤول محلي بكلمة مرور بدلًا من ذلك.يضبط
develop/dev.env بالفعل ADMIN_PRIVILEGE_AVAILABLE=true، لذا يمكن للمسؤولين فتح لوحة الإدارة دون إعداد إضافي.الإعداد (dev.rc)
يحتوي develop/dev.rc بجوار dev.env على مفاتيح بيئة التطوير، مثل overleaf.rc في Overleaf Toolkit. غيّر قيمة وشغّل bin/dev مجددًا لتطبيقها؛ والميزة المعطّلة توقف حاوياتها أيضًا.
تحتفظ كل ميزة بملف
docker-compose.yml وملفاتها الأخرى في مجلد خاص بها: authentication/ldap وauthentication/saml وmail وs3 وhoppscotch وgrafana. والميزة التي تحتاج إلى إعداد في web بلا متغير بيئة تربط ملفًا في /etc/overleaf/settings.d/، ويدمجها develop/settings.dev-env.cjs جميعًا. تمر جميع سكربتات bin/* عبر bin/docker-compose الذي يضيف ملفات الميزات المفعّلة. استدعِ bin/docker-compose بدلًا من docker compose عندما تحتاج إلى أمر compose بنفسك.
المنافذ
يستمع الموقع ووحدة تحكم RustFS وHoppscotch على127.0.0.1 للمضيف؛ وعلى جهاز بعيد، أعِد توجيه منافذها أولًا، مثلًا ssh -L 9001:localhost:9001 <host>. يستخدم الموقع OVERLEAF_PORT من dev.rc، لذا أضف المنفذ إلى العناوين أدناه إذا غيّرته.
يقدّم الموقع Mailpit وGrafana وMongo Express وRedisInsight على مساراتها الخاصة عبر webpack-dev-server، لذا لا تحتاج إلى منافذ خاصة بها. بعد تسجيل الدخول، تشير إليها قائمة Dev tools في شريط التنقل بالموقع؛ وتُستبعد الصفحة التي تكون ميزتها معطّلة في
dev.rc. يوضح إعداد أدوات التطوير ما تفعله كل منها.
لا يمكن الوصول إلى واجهة S3 API (المنفذ 9000) وSMTP (المنفذ 1025) إلا داخل شبكة Docker. تُنشر Mongo (27017) وRedis (6379) وMongo Express (8081) وRedisInsight (5540) وgit-bridge (8000) على 127.0.0.1 للمضيف فقط.
TeX Live
الترجمة في بيئة معزولة مفعّلة افتراضيًا: يضبطdevelop/dev.env القيمة SANDBOXED_COMPILES=true والصورتين ghcr.io/ayaka-notes/texlive-full:2026.1 وghcr.io/ayaka-notes/texlive-full:2025.1. لا يسحب clsi الصور بنفسه، لذا اسحبها مرة واحدة:
dev.env أيضًا تحويلات Pandoc باستخدام PANDOC_IMAGE=overleaf-pandoc:local. ابنِ هذه الصورة مرة واحدة من جذر المستودع:
.env في المجلد develop يحتوي على DOCKER_SOCKET_PATH=/var/run/docker.sock.raw
التطوير
لتجنب تشغيلbin/build && bin/up بعد كل تغيير في الشيفرة، يمكنك تشغيل Overleaf Community Edition في وضع التطوير، حيث تُحدَّث الخدمات تلقائيًا عند تغيير الشيفرة.
للقيام بذلك، استخدم السكربت المضمّن bin/dev:
node --watch، الذي يراقب الشيفرة تلقائيًا ويعيد تشغيل الخدمات عند الحاجة. شغّله مجددًا بعد تغيير dev.rc.
لتحسين الأداء، يمكنك تشغيل مجموعة فرعية فقط من الخدمات في وضع التطوير عن طريق تمرير قائمة مفصولة بمسافات إلى السكربت bin/dev:
سيؤدي تشغيل خدمة
web في وضع التطوير إلى تحديث خدمة web فقط عند تغيير شيفرة الواجهة الخلفية. ولتحديث شيفرة الواجهة الأمامية تلقائيًا أيضًا، تأكد من تشغيل خدمة webpack في وضع التطوير كذلك.bin/i18n، راجع تحديث ترجمات i18n.
تصحيح الأخطاء
عند التشغيل في وضع التطوير تكشف معظم الخدمات منفذ تصحيح يمكنك ربط مصحّح به، مثل أداة الفحص في Chrome Dev Tools أو مصحّح مدمج في بيئة تطوير. يعرض الجدول التالي المنفذ المكشوف على127.0.0.1 في الجهاز المضيف لكل خدمة:
للاتصال بخدمة باستخدام التصحيح عن بُعد في Chrome، انتقل إلى chrome://inspect/ وتأكد من تحديد Discover network targets. ثم انقر على Configure… وأضف إدخالًا
localhost:[service port] لكل خدمة تريد ربط مصحح الأخطاء بها.
بعد إضافة الإدخال، ستظهر الخدمة كـ Remote Target يمكنك فحصها وتصحيح أخطائها.
السجلات
يتابع السكربتbin/logs السجلات وينسّقها باستخدام bunyan. كما يحتاج إلى ggrep، وهو اسم GNU grep عند تثبيته عبر Homebrew على macOS؛ ولا يحتوي Ubuntu على الأمر ggrep.
bin/docker-compose بدلًا من docker compose حتى يُعثر أيضًا على خدمات الميزات في dev.rc (mailpit وrustfs وldap وsaml وhoppscotch وgrafana مع Prometheus وLoki والمصدّرات).
مع GRAFANA_ENABLED=true تكون سجلات كل حاوية موجودة أيضًا في Grafana، حيث يمكن تصفيتها حسب الخدمة والمستوى والنص، راجع إعداد أدوات التطوير.

