Loomix
المستنداتدليل المطوريندليل النشر الشامل عبر Docker لجميع الخدمات العشر

🐳 دليل النشر الكامل عبر Docker Compose

دليل عملي وتفصيلي لنشر منظومة Loomix بجميع خدماتها العشر على خادم إنتاجي افتراضي (VPS) بنقرة واحدة وبأعلى معايير الأمان والاستقرار.

1. المتطلبات الأساسية للخادم (Prerequisites)

قبل البدء، تأكد من توفر خادم افتراضي يعمل بنظام Linux (يوصى بـ Ubuntu 22.04 LTS أو 24.04 LTS) مع المواصفات التالية:

  • الحد الأدنى للذاكرة العشوائية: 4GB RAM مع تفعيل ذاكرة Swap بحجم 4GB على الأقل (أو 8GB RAM للأداء الأمثل).
  • المعالج: 2 vCPU كحد أدنى (يوصى بـ 4 vCPU لعمليات البناء السريعة).

صلاحيات الوصول إلى مقبس Docker (Docker Socket)

تأكد من تثبيت Docker و Docker Compose وإضافة المستخدم الحالي إلى مجموعة docker.

صلاحيات الوصول إلى مقبس Docker (Docker Socket)
bash
sudo usermod -aG docker $USER
newgrp docker          # or log out and SSH back in
docker ps              # should work without sudo

2. نقل كود المشروع إلى الخادم

يمكنك نقل ملفات المشروع إلى الخادم بإحدى الطريقتين التاليتين:

الطريقة الأولى: الاستنساخ المباشر عبر Git (الموصى بها)

تأمين المستودع والملفات الحساسة

أمر استنساخ المستودع عبر Git:
bash
git clone https://github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>.git
cd <YOUR_REPOSITORY_NAME>

الاستنساخ من المستودع الخاص عبر مفاتيح SSH

  • 1. أنشئ زوج مفاتيح SSH على الخادم: ssh-keygen -t ed25519
  • 2. اعرض المفتاح العام وانسخه: cat ~/.ssh/id_ed25519.pub
  • 3. أضف المفتاح العام إلى Deploy Keys في مستودع GitHub الخاص بك.
  • 4. استنسخ المستودع مباشرة عبر SSH.
أمر الاستنساخ عبر SSH:
bash
git clone git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>.git
cd <YOUR_REPOSITORY_NAME>

الاستنساخ باستخدام رمز الوصول الشخصي (Personal Access Token)

أمر الاستنساخ عبر PAT:
bash
git clone https://<YOUR_GITHUB_USERNAME>:<PERSONAL_ACCESS_TOKEN>@github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>.git
cd <YOUR_REPOSITORY_NAME>

الطريقة الثانية: الرفع اليدوي لملف الأرشيف (ZIP / Tarball)

إذا قمت بتنزيل ملف الأرشيف، يمكنك نقله وفك ضغطه على الخادم:

أمر الرفع عبر SCP أو rsync:
bash
rsync -avz --exclude 'node_modules' --exclude '.git' --exclude '.next' ./ user@your_vps_ip:/root/next-strapi-medusa

3. معالج التثبيت والتهيئة التلقائي (Quick Setup Wizard)

لتسهيل عملية النشر، وفرنا سكريبت الإعداد الشامل server-setup.sh الذي يتولى تهيئة Swap، فحص المنافذ، وتثبيت الحاويات خطوة بخطوة:

تشغيل معالج التثبيت التلقائي:
bash
chmod +x server-setup.sh
bash server-setup.sh
نصيحة احترافية:
يقوم المعالج بفحص موارد النظام تلقائياً وتوليد كلمات مرور عشوائية قوية للمفاتيح وقواعد البيانات وحفظها في ملف .env الخاص بك.

4. اختيار ملف النشر المناسب (Deployment Profiles)

يدعم النظام 3 ملفات تعريفية للنشر (Profiles) تناسب مختلف البيئات من التطوير المحلي إلى الإنتاج الضخم:

هل تحتاج إلى اسم نطاق (Domain Name) مخصص؟
نعم، في ملف التعريف B و C يُنصح بربط نطاق حقيقي لتوليد شهادات SSL التلقائية عبر Let's Encrypt وحماية جلسات الكوكيز.
الموصى به لمعظم الخوادم

يستخدم خادماً واحداً (Single VPS) مع نطاقات فرعية تلقائية أو نطاقك الخاص، مع بوابة Caddy وشهادات SSL مجانية.

خطوات تفعيل الملف B:

  • 1. عيّن سجلات DNS (A Records) لنطاقاتك لتشير إلى عنوان IP الخادم.
  • 2. اختر الملف B أثناء تشغيل معالج server-setup.sh.
  • 3. أدخل نطاقك الأساسي (مثل yourdomain.com).
  • 4. سيتولى Caddy استخراج شهادات SSL تلقائياً لجميع الخدمات العشر.
  • 5. جميع لوحات الإدارة ستكون مفعلة ومحمية ببروتوكول HTTPS.
.env (مقتطف الملف B)
env
# Profile B: VM / LAN HTTPS (.local hostnames) - Recommended ★
 
STOREFRONT_PUBLIC_URL=https://store.local
MEDUSA_BACKEND_PUBLIC_URL=https://api.local
STRAPI_PUBLIC_URL=https://admin.local
MEILISEARCH_PUBLIC_URL=https://search.local
MINIO_PUBLIC_URL=https://api.local/minio/mystore
GOOGLE_CALLBACK_URL=https://store.local/ir/account/auth/callback
 
STOREFRONT_URL=http://storefront:8000
MEDUSA_NODE_ENV=production
MEDUSA_ALLOW_HTTP_COOKIES=false
CLOUDFLARE_TUNNEL_TOKEN=
عناوين الإدارة لملف التعريف B:
• المتجر: https://yourdomain.com
• Medusa: https://api.yourdomain.com/app
• Strapi: https://admin.yourdomain.com/admin
• Umami: https://analytics.yourdomain.com
• OpenObserve: https://monitor.yourdomain.com

حماية الواجهة عبر Cloudflare Edge Hardening

قبل توجيه الـ DNS إلى Cloudflare:

تأكد من ضبط SSL في Cloudflare على وضع Full (Strict) لمنع حلقات إعادة التوجيه اللانهائية (Redirect Loops) مع شهادات Caddy الداخلية.

إعدادات Cloudflare بعد تشغيل البيئة:

• وضع تشفير SSL/TLS: اضبطه على Full (Strict). • تفعيل WebSockets: مفعّل افتراضياً في Cloudflare لضمان عمل واجهة Next.js الحية.

مصادقة HTTP الأساسية وحماية حافة Caddy:

• لوحة إدارة Strapi (admin.yourdomain.com/admin): محمية تلقائياً بمصادقة Basic Auth إضافية لمنع محاولات التسلل والتخمين.

توليد تجزئة كلمة مرور Caddy المشفرة (Bcrypt Hash)
bash
docker run --rm caddy:latest caddy hash-password --plaintext "your_secret_password"

مصفوفة العناوين والمنافذ حسب ملف النشر

الخدمةالملف A (محلي)الملف B (خادم واحد)الملف C (مؤسسي)
متجر Next.jshttp://<VM_IP>:8000https://store.localhttps://yourdomain.com
الواجهة الخلفية لـ Medusahttp://<VM_IP>:9000/apphttps://api.local/apphttps://api.yourdomain.com/app
لوحة إدارة Strapi CMShttp://<VM_IP>:1337/adminhttps://admin.local/adminhttps://admin.yourdomain.com/admin
تحليلات Umamihttp://<VM_IP>:3005https://analytics.localhttps://analytics.yourdomain.com
مراقبة OpenObservehttp://<VM_IP>:5080https://monitor.localhttps://monitor.yourdomain.com
محرك البحث Meilisearch127.0.0.1:7700https://search.localhttps://search.yourdomain.com

دلالة كل رابط عام في ملف .env:

  • STOREFRONT_PUBLIC_URL: واجهة متجر Next.js (المنفذ 8000 أو الرابط العام).
  • MEDUSA_BACKEND_PUBLIC_URL: واجهة برمجة Medusa ولوحة الإدارة.
  • STRAPI_PUBLIC_URL: لوحة إدارة Strapi CMS ومعاينة الكتل.
  • MEILISEARCH_PUBLIC_URL: رابط محرك البحث العام للواجهة.
  • MINIO_PUBLIC_URL: الرابط العام للملفات والوسائط المرفوعة.
  • STOREFRONT_URL: رابط داخلي فقط داخل شبكة Docker (http://storefront:3000).

المتغيرات الإلزامية قبل بدء المرحلة 1:

• المفاتيح السرية (openssl rand -hex 32): توليد مفاتيح عشوائية لكل من JWT ومفاتيح تشفير قواعد البيانات.

اترك هذه المتغيرات فارغة حتى تصل لمرحلتها المخصصة:

• المرحلة 4: STRAPI_API_TOKEN_FOR_MEDUSA و STRAPI_API_TOKEN_FOR_FRONT. • المرحلة 6: NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY.

قاعدة لوحة تحكم Medusa: حافظ دائماً على قيمة MEDUSA_ADMIN_ONBOARDING_TYPE بالشكل الافتراضي.

5. أتمتة البناء والنشر عبر GitHub Actions CI/CD

يتضمن المشروع خطوط أنابيب GitHub Actions جاهزة لبناء صور Docker ودفعها إلى سجل الحاويات ونشرها تلقائياً على خادمك:

  1. أضف الأسرار التالية إلى إعدادات المستودع (Repository Secrets): SERVER_HOST و SERVER_USER و SSH_PRIVATE_KEY.
  2. عند الدفع إلى الفرع الرئيسي (main branch)، يتم بناء حاوية Next.js وحاوية Medusa واختبارهما تلقائياً.
  3. يتم إرسال إشعار تحديث للخادم وتشغيل docker compose pull و up -d لإعادة التشغيل بدون توقف (Zero-Downtime Deployment).
  4. 4. (مستودع خاص) قم بإنشاء رمز وصول شخصي GitHub Personal Access Token (Classic) بصلاحيات read:packages لتسجيل الدخول إلى GHCR على الخادم.
تسجيل دخول Docker إلى سجل GHCR على خادم VPS
bash
echo "<YOUR_PAT>" | docker login ghcr.io -u <YOUR_GITHUB_USERNAME> --password-stdin

مراحل النشر التفصيلية (Phases 1-10)

المرحلةالخدمات التي يتم تشغيلهاالملف Aالملف B / C (الإنتاج والشبكة المحلية)
المرحلة 1:قواعد البيانات والبنية الأساسية (Postgres, Redis, MinIO, Meilisearch)✅✅
المرحلة 2:خادم Caddy العكسي والشهادات التلقائية• تخطٍّ (غير مطلوب في الملف A)• تشغيل فوري بعد المرحلة 1 وقبل Strapi
المرحلة 3:محرك Strapi CMS (سحب الصورة من GHCR)✅✅
المرحلة 4:توليد توكنات Stra API وحفظها في .env✅✅
المرحلة 5:الخلفية التجارية Medusa 2.0 (سحب الصورة من GHCR)✅✅
المرحلة 6:توليد مفتاح Medusa القابل للنشر وحفظه في .env✅✅
المرحلة 7:استخراج مفتاح البحث العام لـ Meilisearch✅✅
المرحلة 8:تحليلات Umami المستقلة (قبل تشغيل المتجر)اختياري✅
المرحلة 9:واجهة المتجر Next.js (بناء ونشر عبر GitHub Actions)✅✅
المرحلة 10:منظومة المراقبة وسجلات التشغيل (OpenObserve, Vector, cAdvisor)اختياريموصى به

المرحلة 1: تشغيل قواعد البيانات (PostgreSQL و Redis)

تشغيل حاويات قاعدة بيانات PostgreSQL المشتركة مع قواعد بيانات منفصلة لكل من Medusa وStrapi وUmami، بالإضافة إلى خادم Redis للجلسات والتخزين المؤقت.

أمر تشغيل المرحلة 1:
bash
docker compose up -d postgres redis meilisearch minio minio-setup

انتظر حتى تصبح جميع الخدمات في حالة صحية ممتازة: docker compose ps

المرحلة 2: تشغيل بوابة Caddy وإعداد شهادات SSL

تشغيل بوابة Caddy العكسية للتوجيه التلقائي واستخراج وتجديد شهادات Let's Encrypt مجاناً لجميع النطاقات.

أمر تشغيل المرحلة 2:
bash
docker compose up -d caddy
docker compose logs -f caddy

تكوين ملف hosts في Windows للملف B:

افتح الملف C:\Windows\System32\drivers\etc\hosts بصلاحيات مدير النظام (Administrator) وأضف النطاقات المحلية.

المرحلة 3: تشغيل Strapi CMS v5

سحب وتشغيل حاوية Strapi CMS، وانتظار اكتمال بناء الإدارة وجاهزية المنفذ الداخلي 1337.

أمر تشغيل المرحلة 3:
bash
docker compose pull strapi
docker compose up -d strapi
docker compose logs -f strapi

انتظر حتى يستمع الخادم على المنفذ 1337 وتظهر رسالة جاهزية Strapi في السجلات.

المرحلة 4: استخراج وتعيين رموز Strapi API Tokens

توليد الرموز المميزة (API Tokens) المطلوبة للواجهة الأمامية وتعيينها تلقائياً في ملف .env ليتمكن Next.js من قراءة كتل الصفحة الرئيسية.

  1. يتم تشغيل سكريبت strapi-token-init.js لاستخراج التوكن عبر بيئة Node.js الداخلية.
  2. تُحفظ قيمة STRAPI_API_TOKEN في ملف .env ويُعاد تحميل متغيرات البيئة.
  3. 3. لواجهة المتجر (STRAPI_API_TOKEN_FOR_FRONT): أنشئ توكناً بنوع Read-Only وانسخ القيمة إلى .env.

المرحلة 5: تشغيل محرك MedusaJS v2

تشغيل حاوية Medusa، وتنفيذ ترحيلات قاعدة البيانات (Database Migrations)، وإنشاء حساب المسؤول الأول.

أمر تشغيل المرحلة 5:
bash
docker compose pull medusa
docker compose up -d medusa
docker compose logs -f medusa

خطوات التشغيل التلقائي الأول: ترحيل قواعد البيانات db:migrate (يستغرق 2 إلى 5 دقائق حسب سرعة الخادم).

المرحلة 6: إنشاء مفاتيح النشر وقنوات البيع لـ Medusa

استخراج مفتاح النشر (Publishable API Key) وربطه بقناة البيع الافتراضية (Default Sales Channel) لتمكين الواجهة من قراءة المنتجات وسلات الشراء.

  1. تشغيل أمر medusa user وإنشاء مستخدم المشرف بصلاحيات كاملة.
  2. إنشاء مفتاح publishable وتخزينه في متغير NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY.
  3. 3. هام جداً: افتح المفتاح وتوجه إلى Sales Channels واربط قناة المبيعات الافتراضية بالمفتاح.

المرحلة 7: تشغيل محرك البحث Meilisearch

تشغيل حاوية Meilisearch وضبط مفتاح الأمان (Master Key) وفهرسة المنتجات والتصنيفات للبحث فائق السرعة.

أمر تشغيل المرحلة 7:
bash
curl -H "Authorization: Bearer <MEILI_MASTER_KEY>" http://127.0.0.1:7700/keys

انسخ Default Search API Key وضعه في متغير NEXT_PUBLIC_MEILISEARCH_SEARCH_KEY.

المرحلة 8: تشغيل تحليلات Umami

تشغيل منصة تحليلات Umami المعتمدة على الخصوصية، وإنشاء موقع المتجر وتضمين معرف الويب (Website ID) في الواجهة.

أمر تشغيل المرحلة 8:
bash
docker compose up -d umami

افتح لوحة Umami (الملف B: https://analytics.local، الملف C: نطاقك العام) وأنشئ معرف الموقع Website ID.

المرحلة 9: تشغيل واجهة Next.js 16 Storefront

سحب صورة واجهة المتجر وربطها بكافة الخدمات الجاهزة والتأكد من إمكانية الوصول إلى الصفحة الرئيسية بنجاح.

1. وسائط البناء ومفاتيح الـ API:

تضمين متغيرات البيئة العامة مثل مفتاح Medusa ومسار Strapi أثناء البناء.

1. STOREFRONT_BUILD_ARGS (متغيرات وقت البناء)

تحتوي على متغيرات بيئة Next.js العامة. انسخ القالب أعلاه وضع روابط خادمك.

وسائط البناء (Build Arguments):
env
MEDUSA_BACKEND_URL=http://medusa:9000
NEXT_PUBLIC_MEDUSA_BACKEND_URL=https://api.yourdomain.com
NEXT_PUBLIC_STRAPI_URL=https://admin.yourdomain.com
NEXT_PUBLIC_BASE_URL=https://store.yourdomain.com
NEXT_PUBLIC_MEILISEARCH_HOST=https://search.yourdomain.com
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...
NEXT_PUBLIC_MEILISEARCH_SEARCH_KEY=...
NEXT_PUBLIC_UMAMI_WEBSITE_ID=...
NEXT_PUBLIC_DEFAULT_REGION=US
DEFAULT_LOCALE=en-US
NEXT_PUBLIC_MEILISEARCH_INDEX_NAME=products
NEXT_PUBLIC_ENABLE_IRAN_FEATURES=false

2. رابط السجل (REGISTRY_URL)

رابط سجل الكتل المعيارية. القيمة الافتراضية: سجل Loomix Blocks العام.

3. GITHUB_PAT (اختياري)

رمز وصول شخصي على GitHub بصلاحيات repo في حال استخدام مستودع خاص.

4. مسار النشر على الخادم (DEPLOY_PATH)

المسار المطلق لمجلد المشروع على خادم Linux VPS الخاص بك (مثال: /home/ubuntu/loomix).

2. بناء الصورة بحجم فائق الصغر:

استخدام ميزة Standalone Output في Next.js لتقليل حجم الحاوية لأقل من 150MB.

3. فحص الجاهزية واستقرار الشبكة:

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

4. تشغيل الواجهة الإنتاجية:

أمر تشغيل حاوية الواجهة:
bash
docker compose pull storefront
docker compose up -d storefront

المرحلة 10: منظومة المراقبة والتحليل (OpenObserve & Vector)

تشغيل وكيل جمع السجلات Vector ومحرك OpenObserve لمراقبة أداء الحاويات، استهلاك الذاكرة، وأخطاء السيرفر لحظياً.

أمر تشغيل المرحلة 10:
bash
docker compose up -d openobserve vector cadvisor docker-stats-exporter

لوحة مؤشرات OpenObserve المركزية:

افتح https://monitor.yourdomain.com (الملف C) أو https://monitor.local (الملف B).

قنوات القياس والسجلات المجمعة:

docker_logs: سجلات مجمعة لحاويات Docker العشر مع إمكانية البحث النصي الفوري.

caddy_access: حركة زيارات الويب الحية، عناوين IP، وأكواد استجابة HTTP ومعدل الطلبات.

docker_stats: استهلاك الذاكرة والمعالج لكل حاوية في الوقت الفعلي عبر cAdvisor.

host_metrics: استهلاك موارد الخادم الشاملة، مساحة التخزين، وحمل المعالج العام.

تنبيهات الأخطاء الفورية على تيليجرام:

في لوحة OpenObserve، توجه إلى Alerts وأضف Webhook بوت تيليجرام لتلقي التنبيهات الفورية عند حدوث أي خطأ 500.

6. مزامنة البيانات الأولية بين Medusa و Strapi

يتضمن النظام سكريبت مزامنة يقرأ المنتجات والتصنيفات من Medusa وينشئ الكتل المتطابقة لها في Strapi تلقائياً.

تشغيل سكريبت المزامنة الأولي:

شغّل الأمر التالي داخل حاوية Strapi لإنشاء الصفحة الرئيسية الافتراضية والكتل الجاهزة فوراً:

2. مزامنة كتل Loomix المعيارية (sync-loom-component.js)

في لوحة تحكم Strapi Storefront Management، يؤدي النقر على زر المزامنة إلى جلب أحدث الأنماط وتفعيلها.

المتغيرات البيئية لمزامنة الإنتاج:

ضع هذه المتغيرات في ملف website-admin/.env وملف .env الرئيسي للخادم.

متغيرات مزامنة GitHub CI/CD
env
GITHUB_DEPLOY_TOKEN=ghp_your_personal_access_token # Requires 'repo' and 'workflow' scopes
GITHUB_DEPLOY_REPO=your_username/your_repo_name

7. التبديل بين ملفات النشر وتحديث البيئة

إذا أردت الانتقال من الملف A إلى الملف B أو تغيير أسماء النطاقات، اتبع الجدول التالي للخطوات المطلوبة:

نوع التغييرالخدمات المطلوب إعادة تشغيلها
تعديل الروابط العامة في .envإعادة تشغيل Strapi وMedusa والواجهة (إطلاق بناء GitHub Actions أولاً)
تغيير إعداد MEDUSA_ALLOW_HTTP_COOKIESإعادة تشغيل حاوية Medusa فقط
إضافة Caddy (الانتقال من A إلى B)تشغيل Caddy (docker compose up -d caddy) وسحب الصور الجديدة
تعديل ملف hosts المحلي (الملف B)لا يتطلب أي تعديل على الخادم — تعديل ملف hosts في جهازك فقط
مثال على التبديل بين الملفات التعريفية
bash
# 1. Edit .env — switch to Profile B URLs, set MEDUSA_ALLOW_HTTP_COOKIES=false
nano .env
 
# 2. Add hosts entry on Windows
 
# 3. Start Caddy
docker compose up -d caddy
 
# 4. Pull new images:
docker compose pull strapi medusa && docker compose up -d strapi medusa

8. ترقية وتحديث الخدمات إلى أحدث إصدار

لتحديث جميع الحاويات إلى أحدث الصور دون فقدان أي بيانات من قواعد البيانات، شغّل سكريبت التحديث التلقائي server-update.sh.

9. الأوامر المساعدة للإدارة السريعة

أوامر Docker مفيدة لمراقبة السجلات، إعادة التشغيل، والنسخ الاحتياطي السريع:

أوامر الصيانة الدورية:
bash
./setup.sh # On Linux / macOS
.\setup.bat # On Windows

10. خريطة الشبكة الداخلية والمنافذ

المنافذ الداخلية بين الخدمات (Internal Bridge Network):

  • واجهة المتجر Storefront: :8000
  • خادم Medusa API ولوحة الإدارة: :9000
  • نظام إدارة المحتوى Strapi CMS: :1337
  • محرك البحث Meilisearch: :7700
  • لوحة تحكم تخزين MinIO: :9001
  • منصة التحليلات Umami: :3005
  • مراقبة الأداء OpenObserve: :5080

أسماء النطاقات المعالجة بواسطة Caddy:

  • https://store.local -> storefront:8000
  • https://api.local -> medusa:9000
  • https://admin.local -> strapi:1337
  • https://analytics.local -> umami:3000
  • https://monitor.local -> openobserve:5080
  • https://api.local/minio/ -> minio:9000

عزل الحاويات وشبكة loomix-network الخاصة:

تتواصل الحاويات داخلياً بأسماء الخدمات المعيارية (مثل http://medusa:9000 و http://postgres:5432).

ملخص أهم أوامر الإدارة

عرض السجلات اللحظية لجميع الخدمات:
bash
docker compose ps
إعادة تشغيل خدمة محددة:
bash
docker compose logs -f medusa
docker compose logs -f strapi
docker compose logs -f storefront
docker compose logs -f openobserve
إيقاف المنظومة بالكامل:
bash
docker builder prune -f
docker system prune -f
إعادة تشغيل كاملة (مع الحفاظ على البيانات والأحجام)
bash
docker compose down
docker compose up -d