⚡ البدء

ثلاث طرق للبدء، من الأسرع إلى الأكثر مرونة. تنتهي جميعها بلوحة الإدارة والواجهة البرمجية والقاموس محمَّلًا: مع Docker على http://localhost:3241 وhttp://localhost:3240، وبدونه على http://localhost:3000 وhttp://localhost:3010.

1. تشغيل الصور المنشورة

لا حاجة إلى نسخة من المستودع — مجلد واحد، وملفان، وDocker:

mkdir vocab-bloom-hub && cd vocab-bloom-hub
curl -fsSLO https://raw.githubusercontent.com/Fristail27/vocab-bloom-hub/main/docker-compose.yml
curl -fsSL  https://raw.githubusercontent.com/Fristail27/vocab-bloom-hub/main/.env.example -o .env

افتح .env وعيّن كلمتي مرور: ADMIN_PASSWORD (تسجيل دخول المدير) وPOSTGRES_PASSWORD (قاعدة البيانات المضمّنة). ثم:

docker compose up -d

التشغيل الأول ينزّل القاموس ويستورده — بضع دقائق. يجيب GET /api/ready بـ 503 إلى أن يكتمل الاستيراد وبـ 200 بعده؛ ثم سجّل الدخول بـ ADMIN_USERNAME / ADMIN_PASSWORD من .env.

curl -s localhost:3240/api/ready            # {"status":"ok"}
curl -s localhost:3240/api/v1/words/run     # القاموس يجيب

# البحث: المداخل المطابقة، وأفضلها أولًا
curl -s 'localhost:3240/api/v1/search?search=run&limit=5'
# الشيء نفسه مع المعاني والأمثلة والترجمات
curl -s 'localhost:3240/api/v1/search/detailed?search=run&with_meanings=true'

2. التشغيل من المستودع

ملف compose نفسه، مبنيًا من المصادر — لنسخة fork أو لتغيير لم يُنشر بعد:

git clone https://github.com/Fristail27/vocab-bloom-hub.git
cd vocab-bloom-hub
cp .env.example .env                           # كلمتا المرور نفسهما
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

3. التشغيل بدون Docker

تشغيل إنتاجي على الجهاز نفسه: Node.js 22.13+، وYarn 4 (corepack enable)، وPostgres يمكنك الوصول إليه (docs/database.md).

git clone https://github.com/Fristail27/vocab-bloom-hub.git
cd vocab-bloom-hub
yarn install
printf 'NODE_ENV=production\nDATABASE_URL=postgres://user:password@localhost:5432/vocab_bloom\nADMIN_USERNAME=admin\nADMIN_PASSWORD=change-me\nNEXT_PUBLIC_BASE_API_URL=http://localhost:3010/api\nDICTIONARY_AUTO_IMPORT=true\n' > .env
yarn build && yarn start                       # الواجهة البرمجية :3010، لوحة الإدارة :3000؛ القاموس يحمّل نفسه عند التشغيل الأول
yarn site:build && yarn start:site             # الموقع الإلكتروني :3020، اختياري، في طرفية أخرى

خلف نطاق وTLS، مع systemd أو PM2: docs/deployment/.

للتطوير

لا حاجة إلى قاعدة بيانات: بدون DATABASE_URL يستخدم الخادم ملف SQLite محليًا، ويُعاد تشغيل كل تطبيق عند التغيير.

printf 'NODE_ENV=development\nADMIN_USERNAME=admin\nADMIN_PASSWORD=change-me\nNEXT_PUBLIC_BASE_API_URL=http://localhost:3010/api\n' > .env
yarn dev                                       # الواجهة البرمجية :3010، لوحة الإدارة :3000، الموقع الإلكتروني :3020

كل ما تبقى للمساهمين: CONTRIBUTING.md.

الخطوات التالية

• التوثيق في صورة موقع، مع مرجع API وساحة للتجربة: vocab-bloom-hub.com.
• نشره على خادم: docs/deployment/ — TLS ووكيل عكسي، وsystemd / PM2، والترقيات.
• قاعدة البيانات: docs/database.md — متطلبات Postgres، والترحيلات، والنسخ الاحتياطي، وتقدير الحجم.
• كل إعداد: docs/environment.md.
• المقاييس والسجلات: docs/observability.md — Prometheus وGrafana بأمر واحد، أو ما لديك.
• قراءة البيانات: docs/api.md، وحزمتا SDK لـ Node.js وPython.

---