انتقل إلى المقال
Aniq-UI

Velraشغّل الوكالة محليًا

شغّل الوكالة محليًا

شغّل حزمتك على جهازك باستخدام Docker.

لحزمة الحزمة الكاملة

Dockerموصى بهالتثبيت اليدوي

قبل أن تبدأ: ثبّت Docker Desktop وافتحه، أو Docker Engine مع Compose.

اطّلع على المتطلبات

  1. نزّل قالبك

    افتح صفحة «قوالبي» ونزّل ملف ZIP الخاص بحزمتك.

    النتيجة المتوقعة: يوجد في مجلد التنزيلات ملف باسم يشبه velra-real-estate-full-stack-….zip.

  2. فك الضغط وافتح المجلد

    افتح الطرفية في مكان ملف ZIP، وفكّ ضغطه، ثم انتقل إلى مجلد velra-real-estate-full-stack. على Windows يمكنك فك الضغط في مستكشف الملفات بدلًا من ذلك، ثم فتح طرفية في المجلد.

    الطرفية
    unzip -q velra-real-estate-full-stack-*.zip
cd velra-real-estate-full-stack

    النتيجة المتوقعة: يعرض المجلد admin-dashboard وback-end وstorefront وdocker-compose.yml، إلى جانب README.md وQUICKSTART.md وLICENSE.md.

    تواجه مشكلة؟

  3. شغّل التطبيقات

    ابنِ واجهة API والموقع العام ولوحة تحكم الوكالة وشغّلها. لا يلزم ضبط أي شيء أولًا. يبني التشغيل الأول ثلاث صور ويملأ قاعدة البيانات بالوكالة التجريبية، وهذا يستغرق بضع دقائق؛ أما التشغيلات اللاحقة فتستغرق ثوانيَ.

    الطرفيةفي velra-real-estate-full-stack
    docker compose up --build

    المنفذ مستخدم بالفعل؟

    إذا توقف التشغيل برسالة ports are not available أو address already in use أو port is already allocated، فهناك برنامج آخر يستخدم 3030 أو 3031 أو 8000. أوقفه، أو أنشئ ملفًا باسم .env في مجلد velra-real-estate-full-stack بجانب docker-compose.yml يحدد المنفذ الذي تريده، مثل ADMIN_PORT=3041 (وSITE_PORT للموقع وAPI_PORT لواجهة API). شغّل docker compose up --build مرة أخرى وافتح التطبيق على منفذه الجديد.

    المنفذ مستخدم بالفعل

    النتيجة المتوقعة: تبقى الخدمات الثلاث قيد التشغيل ويتوقف السجل عن التمرير. اترك هذه الطرفية مفتوحة.

    تواجه مشكلة؟

  4. افتح الموقع العام

    افتح localhost:3030محلي. الإنجليزية على /en والعربية على /ar. ليس للموقع حسابات: تُحفظ المنازل المحفوظة والمقارنة في متصفح الزائر.

    النتيجة المتوقعة: يفتح الموقع على صفحته الرئيسية مع العقارات التجريبية وصورها.

    تواجه مشكلة؟

  5. سجّل الدخول إلى لوحة تحكم الوكالة

    افتح localhost:3031محلي. سجّل الدخول بـ admin@velra.example وكلمة المرور Admin@123. أما للوكيل فاكتب agent@velra.example مع Agent@123. غيّر كليهما قبل أن يصبح التطبيق متاحًا من الإنترنت.

    النتيجة المتوقعة: تفتح لوحة التحكم على نظرتها العامة، مع العقارات المنشورة وآخر الاستفسارات والمعاينات القادمة.

    تواجه مشكلة؟

جولة سريعة

شكل الوكالة التجريبية عندما يعمل كل شيء.

الحسابالبريد الإلكترونيكلمة المرور
المدير العام (Super Admin): كل الصفحات والصلاحياتadmin@velra.exampleAdmin@123
الوكيل: النظرة العامة والعقارات والاستفسارات والمعاينات واستوديو التأثيث وقائمة الأحياءagent@velra.exampleAgent@123

تضيف البيانات الأولية 17 عقارًا (15 منشورًا ومسودتان) مع صورها، و6 أحياء، ومعاينتين معتمدتين للتأثيث، و5 استفسارات، و8 طلبات معاينة، فتفتح كل شاشة وهي ممتلئة. هذه حسابات تجريبية محلية فقط.

أوقف التطبيقات وأعد تشغيلها

اضغط Ctrl+C في الطرفية لإيقاف التطبيقات، أو شغّل هذا الأمر من مجلد velra-real-estate-full-stack. تبقى بياناتك، أي قاعدة البيانات والملفات المرفوعة، في وحدة التخزين velra-data.

الطرفيةفي velra-real-estate-full-stack
docker compose down

أعد التشغيل بالأمر نفسه في الخطوة 3. من دون --build يعيد استخدام الصور التي بنيتها مسبقًا.

الطرفيةفي velra-real-estate-full-stack
docker compose up

حافظ على بياناتك

الأمر docker compose down -v يحذف وحدة البيانات أيضًا. يملأ التشغيل التالي نسخة جديدة من الوكالة التجريبية، ويضيع كل ما أنشأته.

شغّل الموقع العام

هذه الحزمة هي الموقع العام وحده. يقرأ كل شيء من واجهة Velra API، لذلك شغّل واجهة API أولًا. ما لم تبنه بعنوان آخر، يتوقع الموقع واجهة API على http://localhost:8000. واجهة API حزمة منفصلة وليست ضمن هذا التنزيل.

  1. نزّل قالبك

    افتح صفحة «قوالبي» ونزّل ملف ZIP الخاص بالموقع العام.

  2. فك الضغط وافتح المجلد

    الطرفية
    unzip -q velra-website-*.zip
cd velra-website

    النتيجة المتوقعة: يحتوي المجلد على Dockerfile وpackage.json.

    تواجه مشكلة؟

  3. ابنِ الصورة

    قيم NEXT_PUBLIC_* تُدمج في JavaScript الذي يحمّله المتصفح، لذلك هي معاملات بناء. بدونها يستخدم الموقع واجهة API على http://localhost:8000/api ويسمّي نفسه http://localhost:3030. أما لواجهة API في مكان آخر فمرّر عنوانها.

    الطرفيةفي velra-website
    docker build -t velra-website .

    مع واجهة API ونطاق خاصين بك:

    الطرفيةفي velra-website
    docker build -t velra-website --build-arg NEXT_PUBLIC_API_BASE_URL=https://api.your-agency.com/api --build-arg NEXT_PUBLIC_SITE_URL=https://www.your-agency.com --build-arg NEXT_PUBLIC_MEDIA_HOSTNAME=media.your-agency.com .
    تواجه مشكلة؟

  4. شغّله

    داخل الحاوية يكون localhost هو الحاوية نفسها، لذلك يخبر API_INTERNAL_URL خادم الموقع بمكان واجهة API على حاسوبك، لعناوين صفحات العقارات والعرض الأول لصفحة العقار وخريطة الموقع. يجعل --add-host الاسم host.docker.internal يعمل على Linux؛ وهو موجود أصلًا في Docker Desktop. إذا كان المنفذ 3030 مشغولًا فغيّر الرقم الذي على يسار -p، مثل -p 3041:3030، وافتح ذلك المنفذ بدلًا منه، وأضف http://localhost:3041 إلى CORS_ORIGIN في واجهة API.

    الطرفيةفي velra-website
    docker run -p 3030:3030 -e API_INTERNAL_URL=http://host.docker.internal:8000/api --add-host=host.docker.internal:host-gateway velra-website

    النتيجة المتوقعة: يفتح localhost:3030محلي الموقع مع العقارات القادمة من واجهة API الخاصة بك. الإنجليزية على /en والعربية على /ar.

    تواجه مشكلة؟

شغّل لوحة تحكم الوكالة

هذه الحزمة هي لوحة تحكم الوكالة وحدها. كل شاشة تقرأ من واجهة Velra API، لذلك شغّل واجهة API أولًا. ما لم تبنها بعنوان آخر، تتوقع لوحة التحكم واجهة API على http://localhost:8000. واجهة API حزمة منفصلة وليست ضمن هذا التنزيل.

  1. نزّل قالبك

    افتح صفحة «قوالبي» ونزّل ملف ZIP الخاص بلوحة تحكم الوكالة.

  2. فك الضغط وافتح المجلد

    الطرفية
    unzip -q velra-agency-dashboard-*.zip
cd velra-agency-dashboard

    النتيجة المتوقعة: يحتوي المجلد على Dockerfile وpackage.json.

    تواجه مشكلة؟

  3. ابنِ الصورة

    بدون معاملات بناء تستخدم لوحة التحكم واجهة API على http://localhost:8000/api. أما لواجهة API في مكان آخر فمرّر عنوانها، وعنوانها دون /api للإشعارات المباشرة، وعنوان الموقع لرابط «عرض الموقع».

    الطرفيةفي velra-agency-dashboard
    docker build -t velra-dashboard .

    مع واجهة API خاصة بك:

    الطرفيةفي velra-agency-dashboard
    docker build -t velra-dashboard --build-arg NEXT_PUBLIC_API_BASE_URL=https://api.your-domain.com/api --build-arg NEXT_PUBLIC_WEBSOCKET_BASE_URL=https://api.your-domain.com --build-arg NEXT_PUBLIC_MEDIA_HOSTNAME=api.your-domain.com --build-arg NEXT_PUBLIC_SITE_URL=https://your-domain.com .
    تواجه مشكلة؟

  4. شغّلها وسجّل الدخول

    إذا كان المنفذ 3031 مشغولًا فغيّر الرقم الذي على يسار -p، مثل -p 3041:3031، وافتح ذلك المنفذ بدلًا منه، وأضف http://localhost:3041 إلى CORS_ORIGIN في واجهة API (واضبط FRONTEND_URL عليه، وهو العنوان الذي تتصل منه الإشعارات المباشرة).

    الطرفيةفي velra-agency-dashboard
    docker run -p 3031:3031 velra-dashboard

    النتيجة المتوقعة: يفتح localhost:3031محلي نموذج تسجيل الدخول. سجّل الدخول بـ admin@velra.example وكلمة المرور Admin@123، وتقبلهما واجهة API التي مُلئت بالبيانات الأولية.

    تواجه مشكلة؟

شغّل واجهة API

هذه الحزمة هي واجهة NestJS API وحدها، على ملف SQLite محفوظ في وحدة تخزين Docker مع الملفات المرفوعة. الموقع العام ولوحة تحكم الوكالة حزمتان منفصلتان وليستا ضمن هذا التنزيل.

  1. نزّل قالبك

    افتح صفحة «قوالبي» ونزّل ملف ZIP الخاص بواجهة API.

  2. فك الضغط وافتح المجلد

    الطرفية
    unzip -q velra-backend-*.zip
cd velra-backend

    النتيجة المتوقعة: يحتوي المجلد على Dockerfile وdocker-entrypoint.sh وpackage.json.

    تواجه مشكلة؟

  3. ابنِ الصورة

    الطرفيةفي velra-backend
    docker build -t velra-api .
    تواجه مشكلة؟

  4. شغّلها مع الوكالة التجريبية

    تبدأ وحدة التخزين الجديدة بجداول فارغة وبلا حسابات ما لم تطلب الوكالة التجريبية، لذلك أبقِ -e SEED_DEMO_DATA=true في التشغيل الأول. تحفظ وحدة التخزين velra-api-data قاعدة البيانات والملفات المرفوعة بين التشغيلات. إذا كان المنفذ 8000 مشغولًا فغيّر الرقم الذي على يسار -p، مثل -p 8010:8000، وأضف -e PUBLIC_MEDIA_URL=http://localhost:8010/media لتستخدمه عناوين الصور أيضًا. عندها يجب أن تشير واجهتاك الأماميتان إلى http://localhost:8010/api.

    الطرفيةفي velra-backend
    docker run -p 8000:8000 -v velra-api-data:/data -e SEED_DEMO_DATA=true velra-api

    النتيجة المتوقعة: يجيب localhost:8000/api/healthمحلي بـ "status":"ok" و"database":"up".

    تواجه مشكلة؟

تقبل الحاوية الموقع على http://localhost:3030 ولوحة التحكم على http://localhost:3031. على عناوين أخرى، اضبط CORS_ORIGIN (الاثنين، مفصولين بفاصلة) وFRONTEND_URL (لوحة التحكم) باستخدام -e.

لتمنح الحاوية مفاتيحك الخاصة (R2 والذكاء الاصطناعي وMCP)، أنشئ .env من .env.example بالأمر cp .env.example .env، واملأه، وأضف --env-file .env -e NODE_ENV=production إلى docker run:

الطرفيةفي velra-backend
docker run -p 8000:8000 -v velra-api-data:/data -e SEED_DEMO_DATA=true --env-file .env -e NODE_ENV=production velra-api

القيمة المعطاة بـ -e تتغلب على الاسم نفسه في الملف، لذلك تعمل الحاوية في وضع الإنتاج مهما كان في .env، وتنقل المسارات النسبية في الملف (SQLITE_DATABASE وMEDIA_UPLOAD_DIR) إلى وحدة التخزين. بدون JWT_SECRET خاص بك، أو مع القيمة الموجودة في المثال، تولّد الحاوية سرًا وتحفظه في وحدة التخزين، فتبقى تسجيلات الدخول صالحة بعد إعادة التشغيل.

التالي

توقفت عند خطوة؟

ابحث عن الحل قبل أن تبدأ من جديد.

حل المشكلات

تفضيلات ملفات تعريف الارتباط

نستخدم ملفات تعريف الارتباط لتعزيز تجربة التصفح الخاصة بك وتحليل حركة المرور على الموقع وتخصيص المحتوى. بالنقر على "قبول الكل"، فإنك توافق على استخدامنا لملفات تعريف الارتباط للتحليلات والإعلانات المخصصة.