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

متغيرات البيئة

تستخدم كل مشاريع ChurchApps ملف .env للإعدادات المحلية. يتضمن كل مشروع ملفًا نموذجيًا تنسخه ثم تخصّصه. تغطي هذه الصفحة متغيرات البيئة الخاصة بواجهات برمجة التطبيقات وتطبيقات الويب وتطبيقات الجوال، بما في ذلك كيفية الاختيار بين الهدف التجريبي والهدف المحلي.

قبل أن تبدأ

النمط العام​

  1. ابحث عن dotenv.sample.txt أو .env.sample في جذر المشروع.
  2. انسخه إلى .env.
  3. عدّل القيم حسب الحاجة.
# مثال لمشروع يحتوي على .env.sample
cp .env.sample .env

# مثال لمشروع يحتوي على dotenv.sample.txt
cp dotenv.sample.txt .env
تحذير

لا تُضف ملفات .env أبدًا إلى نظام التحكم في الإصدارات. فهي تحتوي على بيانات حساسة مثل بيانات اعتماد قاعدة البيانات ومفاتيح واجهات البرمجة وأسرار JWT. تتضمن جميع مشاريع ChurchApps الملف .env في .gitignore، لكن تأكد دائمًا قبل إجراء الإيداع (commit).

اختيار هدف واجهة برمجة التطبيقات​

القرار الأهم هو تحديد المكان الذي تتجه إليه الواجهة الأمامية عند إجراء استدعاءات واجهة برمجة التطبيقات. هناك خياران:

الخيار 1: واجهات برمجة التطبيقات التجريبية (موصى به لتطوير الواجهة الأمامية)​

استخدم البيئة التجريبية المشتركة. لا حاجة إلى تشغيل واجهة برمجة تطبيقات محلية أو إعداد قاعدة بيانات. تعمل هذه البيئة بأحدث كود من main، وتُعاد تعبئة بياناتها التجريبية كل ليلة.

# نمط عنوان URL الأساسي
https://api.demo.churchapps.org/{module}

# أمثلة على عناوين URL للوحدات
https://api.demo.churchapps.org/membership
https://api.demo.churchapps.org/attendance
https://api.demo.churchapps.org/content
https://api.demo.churchapps.org/giving
https://api.demo.churchapps.org/messaging
https://api.demo.churchapps.org/doing
تحذير

تم إيقاف بيئة الاختبار (staging) (api.staging.churchapps.org وapi.staging.lessons.church والمضيفات ذات الصلة). قد تظل بعض ملفات .env النموذجية تحتوي على عناوين staging؛ استبدلها بالقيم التجريبية أو المحلية الموضحة في هذه الصفحة. لا توجد واجهة LessonsApi مشتركة وغير إنتاجية -- شغّل LessonsApi محليًا (يستمع على المنفذ 8090) عندما تحتاج إليها.

الخيار 2: واجهة برمجة تطبيقات محلية​

شغّل مشروع Api على جهازك. يتطلب MySQL 8.0 أو أحدث مع قواعد بيانات منشأة لكل وحدة. راجع دليل إعداد واجهة برمجة التطبيقات المحلية.

# نمط عنوان URL الأساسي
http://localhost:8084/{module}

# أمثلة على عناوين URL للوحدات
http://localhost:8084/membership
http://localhost:8084/attendance
http://localhost:8084/content
http://localhost:8084/giving
http://localhost:8084/messaging
http://localhost:8084/doing

متغيرات البيئة لواجهة برمجة التطبيقات​

يتضمن مشروع Api الأساسي (.env.sample) أكبر قدر من الإعدادات. فيما يلي المتغيرات الرئيسية:

الإعدادات المشتركة​

المتغيرالوصفمثال
ENVIRONMENTبيئة التشغيلdev
SERVER_PORTمنفذ HTTP لخادم التطوير المحلي8084
ENCRYPTION_KEYمفتاح تشفير بطول 192 بت للبيانات الحساسةaSecretKeyOfExactly192BitsLength
JWT_SECRETالسر المستخدم لتوقيع رموز JSON Web Tokensjwt-secret-dev
FILE_STOREمكان تخزين الملفات المرفوعة (disk أو s3)disk
CORS_ORIGINأصول CORS المسموح بها (* للتطوير المحلي)*

اتصال قاعدة البيانات​

يشير عنوان URL أساسي واحد واجهةَ برمجة التطبيقات إلى MySQL. تستنتج واجهة برمجة التطبيقات قاعدة بيانات واحدة لكل وحدة (/membership و/attendance و/content و/giving و/messaging و/doing و/reporting) من هذا العنوان الأساسي.

المتغيرمثال
API_DATABASE_URLmysql://root:password@localhost:3306
نصيحة

حدّث root:password ببيانات اعتماد MySQL الفعلية لديك. يجب أن توجد قاعدة بيانات كل وحدة قبل تشغيل واجهة برمجة التطبيقات. استخدم npm run initdb لإنشاء المخطط لجميع الوحدات، أو npm run initdb:membership لوحدة واحدة.

إعدادات WebSocket​

المتغيرالوصفمثال
SOCKET_PORTالمنفذ الخاص بخادم WebSocket8087
SOCKET_URLعنوان WebSocket الذي يتصل به العملاءws://localhost:8087

متغيرات البيئة لتطبيقات الويب​

B1Admin (React + Vite)​

الملف النموذجي: .env.sample

المتغيرالوصفمثال (تجريبي)
REACT_APP_STAGEاسم البيئةdemo
PORTمنفذ خادم التطوير3101
REACT_APP_API_BASEعنوان URL أساسي واحد لجميع واجهات برمجة تطبيقات ChurchApps (تُلحق تلقائيًا /membership و/attendance و/content و/giving و/messaging و/doing و/reporting)https://api.demo.churchapps.org
REACT_APP_CONTENT_ROOTعنوان URL لتقديم المحتوىhttps://democontent.churchapps.org
REACT_APP_GOOGLE_ANALYTICSمعرّف Google Analytics (اختياري)UA-123456789-1

للتطوير باستخدام واجهة برمجة تطبيقات محلية، وجّه عنوان URL الأساسي إلى المجموعة المحلية لديك:

REACT_APP_API_BASE=http://localhost:8084

B1App (Next.js)​

الملف النموذجي: .env.sample

المتغيرالوصفمثال (تجريبي)
NEXT_PUBLIC_API_BASEعنوان URL أساسي واحد لجميع واجهات برمجة تطبيقات ChurchApps (تُلحق تلقائيًا /membership و/attendance و/content و/giving و/messaging و/doing و/reporting)https://api.demo.churchapps.org
NEXT_PUBLIC_CONTENT_ROOTعنوان URL لتقديم المحتوىhttps://democontent.churchapps.org
NEXT_PUBLIC_GOOGLE_ANALYTICSمعرّف Google Analytics (اختياري)UA-123456789-1
معلومة

يتطلب Next.js البادئة NEXT_PUBLIC_ لأي متغير بيئة يجب أن يكون متاحًا في المتصفح. لا تحتاج المتغيرات الخاصة بالخادم فقط إلى هذه البادئة.

LessonsApp (Next.js)​

الملف النموذجي: dotenv.sample.txt

المتغيرالوصفمثال (LessonsApi محلية)
STAGEمرحلة البيئة (اتركه غير محدد أو اجعله dev للتطوير المحلي)dev
NEXT_PUBLIC_LESSONS_APIعنوان URL لواجهة Lessons APIhttp://localhost:8090
NEXT_PUBLIC_CONTENT_ROOTعنوان URL لتقديم المحتوىhttp://localhost:8090/content
NEXT_PUBLIC_API_BASEعنوان URL الأساسي لواجهة برمجة تطبيقات ChurchApps المستخدمة لتسجيل الدخول (يُعتمد فقط عندما يكون STAGE غير محدد أو dev)https://api.demo.churchapps.org

متغيرات البيئة لتطبيقات الجوال​

B1Checkin (React Native / Expo)​

الملف النموذجي: dotenv.sample.txt

المتغيرالوصفمثال
EXPO_PUBLIC_STAGEيحدد مجموعة واجهات برمجة التطبيقات التي يتصل بها التطبيق: dev (واجهة محلية على http://127.0.0.1:8084)، أو staging، أو prod (الافتراضي عند عدم التعيين)dev

يستخدم B1Checkin وحدتي Membership وAttendance من واجهة برمجة التطبيقات فقط، إضافةً إلى عنوان URL لتقديم المحتوى؛ وتُحدَّد عناوينها لكل مرحلة في src/helpers/EnvironmentHelper.ts.

معلومة

يدرج Expo فقط المتغيرات ذات البادئة EXPO_PUBLIC_ في حزمة التطبيق. أعد تشغيل خادم التطوير باستخدام yarn start --reset-cache بعد تغيير .env.


مرجع سريع: مواقع الملفات النموذجية​

المشروعالملف النموذجي
Api.env.sample
B1Admin.env.sample
B1App.env.sample
B1Checkindotenv.sample.txt
LessonsAppdotenv.sample.txt
AskApidotenv.sample.txt