تخطي إلى المحتوى الرئيسي

الاستضافة الذاتية على Railway

تنشر ChurchApps قالب Railway بنقرة واحدة يمنح كنيستك نسخة خاصة بها من B1 Admin وبوابة أعضاء B1 وواجهة البرمجة (API) وقاعدة بيانات MySQL، وكل ذلك يعمل على بنية تحتية تملكها وتدفع ثمنها مباشرةً. يوصلك هذا الدليل إلى مرحلة التشغيل خلال نحو 15 دقيقة، ثم يشرح إعدادات ما بعد النشر التي تحتاجها معظم الكنائس في النهاية.

البدء السريع​

Deploy on Railway

  1. انقر على زر Deploy on Railway أعلاه.
  2. سجّل الدخول إلى Railway (أو أنشئ حسابًا مجانيًا) وأضف وسيلة دفع.
  3. انقر على Deploy دون تغيير أي شيء، فكل متغير له قيمة افتراضية مناسبة.
  4. انتظر من 5 إلى 10 دقائق حتى تصبح الخدمات الأربع باللون الأخضر.
  5. افتح عنوان URL لخدمة B1Admin، وانقر على Register، وأنشئ حسابك. يصبح أول حساب تنشئه تلقائيًا مسؤول الخادم.
  6. اتبع التعليمات داخل التطبيق لإنشاء أول كنيسة لك.

وهذا كل شيء. أصبح لديك الآن نسخة ChurchApps تعمل بكامل طاقتها. كل ما يلي تحسينات اختيارية.

نصيحة

النشر حاليًا في مرحلة التجريب (beta). إذا واجهتَ أمرًا لا تغطيه هذه الوثائق، فيرجى فتح بلاغ على github.com/ChurchApps/Api/issues مع إرفاق سجلات النشر.

ما تحتاجه

  • حساب مجاني على Railway
  • بطاقة ائتمان مسجلة لدى Railway (نحو 15 إلى 25 دولارًا شهريًا لجماعة صغيرة؛ انظر التكاليف)
  • نحو 15 دقيقة للنشر الأولي
  • اختياري لكنه موصى به بشدة لاحقًا: بيانات اعتماد SMTP ونطاق مخصص

ما الذي يتم نشره​

يُنشئ القالب أربع خدمات في مشروع Railway واحد:

الخدمةالغرضعنوان URL بعد النشر
MySQLتخزين جميع البيانات (نسخة واحدة، ومخططات متعددة)داخلي فقط
Apiالواجهة الخلفية للعضوية والمحتوى والعطاء والحضور وغيرهاhttps://api-<id>.up.railway.app
B1Adminتطبيق الويب للموظفين والمشرفينhttps://b1admin-<id>.up.railway.app
B1Appتطبيق ويب للأعضاء وموقع الكنيسةhttps://b1app-<id>.up.railway.app

تُنشأ مخططات قاعدة البيانات تلقائيًا عند التشغيل الأول، عبر عملية الترحيل (migration) التي تعمل عند بدء تشغيل واجهة البرمجة.

الإعداد لأول مرة​

الآن بعد أن أصبح النظام يعمل، إليك أهم ما تقوم به معظم الكنائس لاحقًا، مرتبًا حسب الأولوية تقريبًا.

1. البريد الإلكتروني (موصى به بشدة)​

من دون بريد إلكتروني، يستطيع الأعضاء التسجيل واستخدام النظام، لكنهم لن يتمكنوا من إعادة تعيين كلمات المرور المنسية، ويجب أن يقوم المشرف بذلك نيابةً عنهم. يستغرق إعداد SMTP نحو 5 دقائق.

في لوحة تحكم Railway، افتح خدمة Api ← Variables، وأضف:

MAIL_SYSTEM=SMTP
SMTP_HOST=<your provider host>
SMTP_USER=<your username>
SMTP_PASS=<your password or API key>
SMTP_SECURE=false
SUPPORT_EMAIL=noreply@yourchurch.org

ثلاثة مزودين يستحق الأمر معرفتهم:

Resend — أبسط خيار مجاني (100 رسالة يوميًا)​

  1. سجّل على resend.com.
  2. تحقق من نطاق إرسال (أو استخدم المرسل التجريبي onboarding@resend.dev للبدء).
  3. أنشئ مفتاح API.
  4. اضبط SMTP_HOST=smtp.resend.com وSMTP_USER=resend وSMTP_PASS=re_xxxxxxxxx.

Gmail — مجاني للاستخدام الشخصي (نحو 500 رسالة يوميًا)​

  1. فعّل المصادقة الثنائية (2-factor auth) على حساب Google.
  2. أنشئ كلمة مرور للتطبيقات (App Password).
  3. اضبط SMTP_HOST=smtp.gmail.com وSMTP_USER=your-address@gmail.com وSMTP_PASS=<كلمة المرور المكونة من 16 حرفًا>.

AWS SES — الأرخص عند الحجم الكبير​

  1. تحقق من نطاق الإرسال في AWS.
  2. اخرج من وضع الاختبار (sandbox) في SES إذا كنت سترسل إلى عناوين غير متحقق منها.
  3. أنشئ بيانات اعتماد SMTP من SES ← SMTP Settings ← Create credentials.
  4. اضبط SMTP_HOST=email-smtp.us-east-2.amazonaws.com وSMTP_USER=AKIA... وSMTP_PASS=<كلمة مرور SES SMTP>.

بعد حفظ المتغيرات، تُعاد عملية نشر خدمة Api تلقائيًا. للتحقق، ابدأ عملية إعادة تعيين كلمة المرور لحساب تجريبي.

تحذير

إذا ضبطت MAIL_SYSTEM=SMTP ببيانات اعتماد خاطئة، فسيبدو التسجيل ناجحًا لكن رسالة التحقق لن تصل أبدًا. إما أن تصحح بيانات الاعتماد، أو تُزيل MAIL_SYSTEM للعودة إلى وضع عدم استخدام البريد الإلكتروني.

2. النطاقات المخصصة​

تعمل عناوين *.up.railway.app الافتراضية، لكن معظم الكنائس تريد نطاقاتها الخاصة.

لكل خدمة ويب (B1Admin وB1App):

  1. افتح الخدمة في Railway ← Settings ← Networking.
  2. انقر على + Custom Domain وأدخل اسم المضيف:
    • admin.yourchurch.org لخدمة B1Admin
    • app.yourchurch.org (أو www) لخدمة B1App
  3. أضف سجل CNAME الذي يعرضه Railway إلى مزود DNS لديك.
  4. انتظر بضع دقائق حتى ينتشر DNS. يتولى Railway إصدار شهادة TLS تلقائيًا.

ثم حدّث متغيرات خدمة Api كي تشير الروابط في رسائل البريد إلى النطاقات الجديدة:

B1ADMIN_ROOT=https://admin.yourchurch.org

وفي خدمة B1Admin:

REACT_APP_API_BASE=https://api.yourchurch.org   (if you also set a custom API domain)
REACT_APP_B1_WEBSITE_URL=https://{subdomain}.yourchurch.org

الرمز {subdomain} حرفي، ويُستبدل وقت التشغيل باسم النطاق الفرعي لكل كنيسة (انظر Multi-Site أدناه).

3. تعدد المواقع (عدة كنائس على نسخة واحدة)​

صُممت ChurchApps بنظام تعدد المستأجرين (multi-tenant)، فيمكن لنشر واحد أن يستضيف أي عدد من الكنائس، لكل منها أعضاؤها ومجموعاتها وموقعها الإلكتروني. تُضاف الكنائس الجديدة بالكامل من واجهة المشرف، دون أي تغييرات في البنية التحتية.

إضافة كنائس إضافية​

  1. في B1 Admin، انتقل إلى Settings ← Manage Church ← Switch Church ← Create New.
  2. لكل كنيسة معرّف نطاق فرعي (subdomain slug) فريد (مثل firstchurch وgracecommunity).
  3. تحصل الكنيسة الجديدة على بياناتها وأعضائها وموقعها وإعدادات العطاء الخاصة بها، معزولةً تمامًا عن الكنائس الأخرى في النسخة نفسها.

توجيه كل كنيسة إلى عنوانها الخاص​

هناك طريقتان لعرض الكنائس للجمهور:

النمطالمثالالإعداد
مبني على المسار (يعمل مباشرةً)app.yourchurch.org/firstchurchلا يتطلب إعدادًا إضافيًا
مبني على النطاق الفرعي (روابط أنظف)firstchurch.yourchurch.orgDNS بحرف عام (wildcard) ونطاق مخصص بحرف عام

للتوجيه المبني على النطاق الفرعي في Railway:

  1. في مزود DNS لديك، أنشئ سجل CNAME بحرف عام: *.yourchurch.org → <b1app railway target>.
  2. في Railway، على خدمة B1App ← Settings ← Networking، أضف *.yourchurch.org كنطاق مخصص.
  3. في خدمة B1Admin، اضبط REACT_APP_B1_WEBSITE_URL=https://{subdomain}.yourchurch.org.

بعد إعادة النشر، يُقدَّم موقع كل كنيسة تلقائيًا على <their-subdomain>.yourchurch.org.

معلومة

تتطلب النطاقات المخصصة ذات الحرف العام خطة Railway مدفوعة. يعمل التوجيه المبني على المسار في كل الخطط ويؤدي الوظيفة نفسها، لكن الرابط يبدو أقل أناقة في شريط العناوين.

4. العطاء عبر الإنترنت (Stripe / PayPal)​

يُضبط العطاء لكل كنيسة على حدة داخل واجهة المشرف، وليس عبر متغيرات البيئة، حتى تتمكن كل كنيسة من استخدام حساب التاجر الخاص بها.

  1. احصل على بيانات اعتماد المطورين من Stripe (Developers ← API keys) أو PayPal (My Apps & Credentials).
  2. في B1 Admin، انتقل إلى Settings ← Giving Settings.
  3. اختر مزودك، والصق المفتاحين العام والسري، واضبط طريقة التعامل مع الرسوم.
  4. يمكنك اختياريًا إضافة GOOGLE_RECAPTCHA_SECRET_KEY إلى خدمة Api في Railway لحماية نماذج التبرع العامة من الروبوتات.

5. تخزين الملفات​

يُنشئ القالب وحدة تخزين دائمة (volume) بسعة 1 جيجابايت متصلة بخدمة Api، لتخزين صور الأعضاء وملفات الخطب والمستندات المرفوعة.

لتوسيعها، افتح خدمة Api ← Volumes ← واضبط شريط الحجم.

للنشرات الأكبر (100 جيجابايت فأكثر، أو عمليات رفع متزامنة كثيرة)، انتقل إلى S3 بضبط هذه المتغيرات على خدمة Api:

FILE_STORE=S3
AWS_S3_BUCKET=<your-bucket>
AWS_ACCESS_KEY_ID=<key>
AWS_SECRET_ACCESS_KEY=<secret>
AWS_REGION=us-east-2

لا تنتقل الملفات الموجودة في وحدة التخزين تلقائيًا؛ انسخها إلى الحاوية (bucket) قبل تغيير المتغير.

6. تكاملات الميزات الاختيارية​

تفعّل هذه المتغيرات ميزات محددة، ويمكن إضافتها لاحقًا كلها عبر لوحة تحكم Railway. اضبطها على خدمة Api.

المتغيرالميزة التي يفعّلها
OPENAI_API_KEY أو OPENROUTER_API_KEYالبحث واقتراحات المحتوى بمساعدة الذكاء الاصطناعي
YOUTUBE_API_KEYالبحث عن خطب YouTube وتضمينها
PEXELS_KEYمنتقي الصور المجانية لمنشئ المواقع
VIMEO_TOKENدعم خطب Vimeo
API_BIBLE_KEYالبحث عن آيات الكتاب المقدس في الدروس والمحتوى
YOUVERSION_API_KEYتكامل YouVersion للكتاب المقدس
WEB_PUSH_PUBLIC_KEY + WEB_PUSH_PRIVATE_KEYإشعارات الدفع في المتصفح (أنشئ زوج مفاتيح VAPID)
HUBSPOT_KEYمزامنة اختيارية مع نظام إدارة العلاقات (CRM) للتسجيلات الجديدة

التحديث​

كل خدمة مرتبطة بمستودع GitHub الخاص بها. تؤدي عمليات الدفع إلى main في ChurchApps/Api أو ChurchApps/B1Admin أو ChurchApps/B1App إلى إعادة نشر تلقائية.

لتثبيت إصدار محدد، غيّر إعداد Branch في كل خدمة إلى وسم (tag) أو فرع إصدار. هذا هو الإعداد الموصى به للإنتاج، لأن النشر التلقائي من main يعني أنك ستحصل على أي عمل غير مكتمل.

التكاليف​

نطاقات واقعية لكنيسة صغيرة (أقل من 200 عضو، وحركة خفيفة):

المكوّنالتكلفة الشهرية التقريبية
الاشتراك الأساسي في Railway5 دولارات
إضافة MySQL5 دولارات + نحو دولار للتخزين
حوسبة 3 خدمات ويب3–10 دولارات مجتمعةً
وحدة تخزين 1 جيجابايت0.25 دولار
المجموعنحو 15–25 دولارًا شهريًا

تزداد التكاليف بشكل خطي مع حجم الحركة، ورفع الصور، وحجم قاعدة البيانات. يعرض Railway الاستخدام المباشر في تبويب Usage الخاص بالمشروع، ويمكنك ضبط حدود الإنفاق هناك للحد من تعرضك للتكاليف.

استكشاف الأخطاء وإصلاحها​

العَرَضالسبب المحتملالحل
فشل البناء مع EBUSY: rmdir '/app/node_modules/.cache'تعارض في جبل ذاكرة التخزين المؤقت لـ Nixpacksاضبط NIXPACKS_NO_CACHE=true على الخدمة المتأثرة
فشل البناء على B1Admin مع Missing: @types/...ملف package-lock.json غير متزامناسحب أحدث نسخة من main
يتوقف نشر Api عند "Deploying"فشل فحص الصحة — /health لا يُرجع 200اعرض سجلات النشر؛ غالبًا متغير بيئة مطلوب مفقود
تقول B1Admin "check your email" لكن لا تصل أي رسالةMAIL_SYSTEM=SMTP مضبوط لكن بيانات الاعتماد مفقودة أو خاطئةصحح بيانات الاعتماد، أو أزل MAIL_SYSTEM لتعطيل البريد الإلكتروني
يعيد تسجيل الدخول التوجيه إلى api.churchapps.orgREACT_APP_STAGE قيمته prodاضبط REACT_APP_STAGE=custom على خدمة B1Admin
تعرض جميع الكنائس ذات النطاقات الفرعية المحتوى نفسهREACT_APP_B1_WEBSITE_URL لا يحتوي على الرمز {subdomain}اضبطه على سبيل المثال https://{subdomain}.yourchurch.org
يعرض النطاق المخصص "Application not found"لم ينتشر DNS بعد، أو شهادة Railway قيد الانتظارانتظر 5 دقائق؛ تحقق من DNS باستخدام dig admin.yourchurch.org

إذا واجهتَ أمرًا غير مدرج في هذه القائمة، فافتح بلاغًا على github.com/ChurchApps/Api/issues مع إرفاق سجلات النشر.

مقالات ذات صلة​