إنتقل إلى المحتوى الرئيسي

إعداد Docker للتطوير

هذا الدليل يشرح كيفية تشغيل شام باص محلياً باستخدام Docker.

نظرة على البنية​

┌─────────────────────────────────────────────────────────────────────────────┐
│                              Docker Compose                                  │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                         تطبيقات الويب                                │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │   │
│  │  │   Customer   │  │  Dashboard   │  │    Admin     │               │   │
│  │  │  Port 3000   │  │  Port 3001   │  │  Port 3002   │               │   │
│  │  └──────────────┘  └──────────────┘  └──────────────┘               │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│  ┌─────────────────────────────────┴───────────────────────────────────┐   │
│  │                         Supabase Stack                               │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐            │   │
│  │  │PostgreSQL│  │  Kong    │  │ GoTrue   │  │PostgREST │            │   │
│  │  │  :5432   │  │  :8000   │  │  :9999   │  │  :3005   │            │   │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘            │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                         المراقبة                                     │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐                           │   │
│  │  │ Grafana  │  │   Loki   │  │GlitchTip │                           │   │
│  │  │  :3030   │  │  :3100   │  │  :8080   │                           │   │
│  │  └──────────┘  └──────────┘  └──────────┘                           │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘

المتطلبات​

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

تشغيل كامل البيئة​

# تشغيل جميع الخدمات
make dev

# أو بدون Make:
docker compose --profile dev up -d

عند بدء البيئة، يشغّل Compose خدمة مؤقتة اسمها db-bootstrap قبل تشغيل auth و rest و storage. هذه الخدمة تقوم الآن بثلاث مهام:

  • مزامنة كلمات مرور حسابات Supabase الداخلية (authenticator و supabase_auth_admin و supabase_storage_admin)
  • تطبيق أي ترحيلات جديدة
  • تطبيق seed مرجعي دائم، ثم seed الديمو للتطوير بشكل افتراضي

يشغل هذا:

  • 3 تطبيقات ويب: Customer (3000), Dashboard (3001), Admin (3002)
  • خدمة بوت تيليجرام: telegram-bot لربط رقم الهاتف مع Chat ID عند ضبط TELEGRAM_BOT_TOKEN
  • Supabase: PostgreSQL, Kong, GoTrue, PostgREST, Realtime, Storage
  • Studio: Supabase Studio على المنفذ 3010
  • المراقبة: Grafana, Loki, GlitchTip

تشغيل Backend فقط​

# تشغيل خدمات Supabase فقط
make supabase-start

# ثم تشغيل التطبيقات محلياً
pnpm dev

روابط الخدمات​

الخدمةالرابطالوصف
بوابة العميلhttp://localhost:3000حجز التذاكر
لوحة الشركاتhttp://localhost:3001إدارة الشركة
لوحة الإدارةhttp://localhost:3002إدارة المنصة
التوثيقhttp://localhost:3003الوثائق
Telegram Botخدمة workerربط تيليجرام للـ OTP
Supabase APIhttp://localhost:8000بوابة API
Supabase Studiohttp://localhost:3010إدارة قاعدة البيانات
Grafanahttp://localhost:3030المراقبة
GlitchTiphttp://localhost:8080تتبع الأخطاء

يمكن فتح تطبيقات Next.js المحلية أيضاً عبر 127.0.0.1 على المنافذ نفسها، وهو المسار الذي تستخدمه اختبارات Chromium المحلية. تضبط التطبيقات الثلاثة allowedDevOrigins لهذا العنوان حتى لا يرفض خادم التطوير ملفات /_next أو HMR بـ HTTP 403. هذا السماح خاص بالتطوير ولا يغير سياسة أصول الإنتاج.

الأوامر الشائعة​

# تشغيل بيئة التطوير
make dev

# إيقاف الخدمات
make stop

# عرض السجلات
make logs

# إعادة بناء التطبيقات
make rebuild

# إعادة تعيين قاعدة البيانات
make db-reset

# إعادة تشغيل bootstrap لقاعدة البيانات (حسابات الخدمة + الترحيلات + seeds)
make db-fix-passwords

# تشغيل الترحيلات
make db-migrate

# ملء البيانات الأولية
make db-seed

# فتح shell قاعدة البيانات
make shell-db

# حذف كل شيء
make clean

Hot Reload​

إعداد Docker يربط ملفات المصدر للتحديث التلقائي:

volumes:
  # المصدر (hot reload)
  - ./apps/customer/src:/app/apps/customer/src:cached
  - ./apps/customer/public:/app/apps/customer/public:cached

  # الحزم المشتركة
  - ./packages:/app/packages:cached

التغييرات على هذه الملفات تعيد البناء تلقائياً:

  • apps/*/src/**/* - كود المصدر
  • packages/*/src/**/* - الحزم المشتركة
  • apps/*/public/**/* - الملفات الثابتة

إدارة قاعدة البيانات​

تشغيل الترحيلات​

make db-migrate

# أو يدوياً عبر Studio
# http://localhost:3010 → SQL Editor

البيانات الأولية​

make db-seed

في بيئة التطوير، يقوم bootstrap الافتراضي أيضاً بملء:

  • 21 مدينة سورية
  • شركات تجريبية
  • مسارات ورحلات نموذجية

الاتصال بـ psql​

make shell-db

# أو مباشرة:
docker exec -it shambus-db psql -U postgres -d postgres

إعداد تطبيقات الموبايل​

للاتصال بـ Docker المحلي من Flutter:

// Android Emulator
static const String supabaseUrl = 'http://10.0.2.2:8000';

// iOS Simulator
static const String supabaseUrl = 'http://localhost:8000';

// جهاز حقيقي (استخدم IP الجهاز)
static const String supabaseUrl = 'http://192.168.1.x:8000';

استكشاف الأخطاء​

المنفذ مستخدم​

# التحقق من المنفذ
lsof -i :3000
lsof -i :5432

التطبيقات لا تعمل​

# التحقق من السجلات
docker compose logs customer

# إعادة بناء تطبيق محدد
docker compose build customer --no-cache
docker compose up -d customer

مشاكل قاعدة البيانات​

# التحقق من جاهزية قاعدة البيانات
docker compose logs db

# اختبار الاتصال
docker exec shambus-db pg_isready

# إعادة تعيين قاعدة البيانات
make db-reset

إذا ظهرت أخطاء مثل:

  • password authentication failed for user "authenticator"
  • password authentication failed for user "supabase_auth_admin"
  • password authentication failed for user "supabase_storage_admin"

فابدأ أولاً بـ:

make db-fix-passwords
docker compose --profile dev up -d auth rest storage kong

هذا يعيد ضبط كلمات مرور حسابات Supabase الداخلية داخل قاعدة البيانات الحالية بدون حذف البيانات أو إعادة إنشاء الـ volumes.

آخر تحديث: أبريل 2026