دليل 2026 لنشر Laravel + Vue: من Docker إلى GitHub Actions وCoolify

إذا كنت تبني مشروع Laravel + Vue بسرعة، لكن كل عملية نشر تجيب معها قلق ومفاجآت، فهذا الدليل لك.

الفكرة هنا ليست فقط "كيف أنشر؟"، بل "كيف أنشر بثقة، بدون تعطيل المستخدمين، ومع خطة تراجع واضحة".

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

• Laravel 12 للـ API ومنطق العمل
• Vue 3 + Vite للواجهة
• Docker لتوحيد البيئة بين الفريق والسيرفر
• GitHub Actions لاختبارات وبناء تلقائي
• Coolify كنظام نشر ذاتي الاستضافة

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

مستوى الصعوبة

متوسط (intermediate) — مناسب لمطور يعرف أساسيات Laravel وVue وGit.

ماذا سننجز فعليًا؟

1. بيئة تطوير محلية مستقرة عبر Docker Compose
2. Dockerfile متعدد المراحل للإنتاج
3. Workflow في GitHub Actions للاختبارات والبناء
4. إعداد نشر التطبيق على Coolify
5. ممارسات ما قبل وبعد النشر (migrations, cache, queues)
6. خطة Rollback عملية عند فشل الإصدار
7. أساسيات المراقبة والتنبيهات

المتطلبات قبل البدء

تأكد من توفر:

• مستودع GitHub فيه مشروع Laravel + Vue
• Docker Engine أو Docker Desktop (إصدار حديث)
• Node.js 20+ للتطوير المحلي
• VPS عليه Docker (Hetzner أو OVH أو DigitalOcean...)
• Coolify مثبت ويعمل
• (اختياري) نطاق أو نطاق فرعي للإنتاج

الإصدارات المقترحة في هذا الدليل:

• PHP 8.3
• Laravel 12
• Vue 3
• Vite 6
• PostgreSQL 16
• Redis 7

الخطوة 1 — تنظيم المشروع للنشر عبر الحاويات

قبل أي شيء، لازم بنية المشروع تكون واضحة. في أغلب مشاريع Laravel + Vue الحديثة:

.
├── app/
├── bootstrap/
├── config/
├── database/
├── public/
├── resources/
├── routes/
├── storage/
├── tests/
├── composer.json
├── package.json
└── vite.config.js

أضف الملفات التالية في الجذر:

• .dockerignore
• Dockerfile
• docker-compose.yml
• docker/ للإعدادات المساندة (nginx + supervisor + entrypoint)

ملف .dockerignore مهم جدًا لتقليل حجم الـ build context:

.git
.github
node_modules
vendor
storage/logs
storage/framework/cache
storage/framework/sessions
storage/framework/views
.env
.env.*

⚠️ تنبيه: لا تضع أسرارك داخل الصورة (image). المتغيرات الحساسة يجب أن تُحقن وقت التشغيل عبر Coolify.

الخطوة 2 — إنشاء Dockerfile متعدد المراحل

الهدف: صورة إنتاج خفيفة وسريعة.

# syntax=docker/dockerfile:1.7
 
FROM node:20-alpine AS frontend_builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY resources ./resources
COPY vite.config.* ./
COPY public ./public
RUN npm run build
 
FROM composer:2.8 AS php_vendor
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader --no-interaction
 
FROM php:8.3-fpm-alpine AS app
RUN apk add --no-cache nginx supervisor postgresql-dev icu-dev libzip-dev oniguruma-dev
RUN docker-php-ext-install pdo pdo_pgsql mbstring intl zip opcache
 
WORKDIR /var/www/html
COPY . .
COPY --from=php_vendor /app/vendor ./vendor
COPY --from=frontend_builder /app/public/build ./public/build
 
RUN chown -R www-data:www-data storage bootstrap/cache
RUN chmod -R 775 storage bootstrap/cache
 
COPY docker/nginx.conf /etc/nginx/http.d/default.conf
COPY docker/supervisord.conf /etc/supervisord.conf
 
EXPOSE 80
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisord.conf"]

لماذا هذا الأسلوب ممتاز؟

• مرحلة للبناء الأمامي (assets) فقط
• مرحلة لاعتماديات PHP فقط
• مرحلة نهائية خفيفة للتشغيل
• زمن نشر أسرع وذاكرة أقل

الخطوة 3 — إعداد Docker Compose للتطوير المحلي

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8080:80"
    env_file:
      - .env
    depends_on:
      - db
      - redis
    volumes:
      - ./:/var/www/html
 
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: noqta
      POSTGRES_USER: noqta
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql/data
 
  redis:
    image: redis:7-alpine
 
volumes:
  pgdata:

تشغيل أولي:

docker compose up -d --build
docker compose exec app php artisan key:generate
docker compose exec app php artisan migrate
docker compose exec app php artisan test

هذه النقطة مهمة: أي شيء لا يمر محليًا داخل Docker غالبًا سيفشل لاحقًا في CI/CD.

🚀 تريد تطبيق نفس البنية على مشروعك بسرعة وبدون أخطاء بنيوية؟ فريق تكامل API في نقطة يساعدك في بناء خط نشر متين من الصفر.

الخطوة 4 — تهيئة Laravel للإنتاج بشكل آمن

في .env.example أو إعدادات Coolify:

APP_ENV=production
APP_DEBUG=false
LOG_LEVEL=info
QUEUE_CONNECTION=redis
CACHE_STORE=redis
SESSION_DRIVER=redis
DB_CONNECTION=pgsql

أنشئ script دخول بسيط:

#!/usr/bin/env bash
set -e
 
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan migrate --force
 
exec "$@"

هذا يضمن أن التطبيق يبدأ وهو مجهّز بالأداء المطلوب.

⚠️ تحذير مهم: migrate --force ممتاز للترقيات العادية، لكن التعديلات المدمرة للبيانات تحتاج استراتيجية تدريجية (expand/contract) وليس نشر مباشر.

الخطوة 5 — بناء CI حقيقي في GitHub Actions

ملف .github/workflows/ci.yml يجب أن يشمل:

• تثبيت PHP وComposer
• تثبيت Node وnpm dependencies
• بناء الواجهة
• تشغيل migrations على قاعدة اختبار
• تشغيل الاختبارات

نموذج مختصر:

name: CI
on:
  pull_request:
  push:
    branches: ["main"]
 
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: testdb
      redis:
        image: redis:7
 
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
      - run: composer install --no-interaction --prefer-dist
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build
      - run: cp .env.example .env && php artisan key:generate
      - run: php artisan migrate --force
      - run: php artisan test --parallel

ولرفع الجودة أكثر، أضف:

• Pint لتنسيق الكود
• Larastan لتحليل ثابت
• ESLint/Type checking للواجهة
• Trivy لفحص الثغرات في الصور

الخطوة 6 — بناء image ونشرها بشكل يمكن تتبعه

أفضل ممارسة: كل إصدار = image tag واضح (SHA).

في workflow منفصل:

• تسجيل دخول GHCR
• بناء image
• رفع tags (latest + sha)

فائدة هذا النهج:

1. تعرف بالضبط أي commit يعمل في الإنتاج
2. rollback في دقائق
3. نفس image من staging إلى production (بدون rebuild)

الخطوة 7 — النشر على Coolify خطوة بخطوة

داخل Coolify:

1. Application جديدة
2. اربط المشروع (GitHub أو GHCR)
3. ضع Dockerfile أو image المبنية مسبقًا
4. أضف Environment Variables
5. عيّن الدومين وشهادة SSL
6. فعّل health check

أضف endpoint بسيط في Laravel:

Route::get('/up', fn () => response()->json(['status' => 'ok']));

إعدادات مهمة:

• health path: /up
• retries: 5
• timeout: 10s
• auto deploy: مفعل على main

💡 نصيحة: اجعل عندك staging على فرع مستقل (مثل staging) لتجربة الإصدار قبل الإنتاج.

الخطوة 8 — ممارسات الأمان والاستقرار قبل Go-Live

أمن التطبيق

• إيقاف debug في الإنتاج
• ضبط CORS بدقة
• تفعيل rate limiting لنقاط تسجيل الدخول
• التأكد من HTTPS فقط

أمن البنية

• نسخ احتياطي يومي لقاعدة البيانات
• جدار ناري يسمح بـ 80/443 فقط
• أقل صلاحيات ممكنة للخدمات

استقرار التشغيل

• مراقبة queue workers (Supervisor)
• رصد failed jobs
• حفظ logs بشكل مركزي

الأداء

• OPcache مفعل
• Redis يعمل فعليًا كـ cache/session/queue
• Laravel caches مفعّلة (config/route/view)

الخطوة 9 — خطة Rollback قابلة للتنفيذ

خطة التراجع ليست وثيقة نظرية، بل إجراء يجب أن تختبره.

سيناريو التراجع:

1. اكتشاف خطأ حرج بعد النشر
2. إيقاف النشر التلقائي مؤقتًا
3. العودة إلى image السابقة المستقرة (SHA)
4. إعادة التحقق من endpoint الصحة + التدفقات الأساسية
5. فتح postmortem وتوثيق السبب والإجراء الوقائي

بخصوص قاعدة البيانات:

• تجنب migrations المدمرة مباشرة
• استخدم feature flags للميزات الكبيرة
• حافظ على توافقية schema لنسخة واحدة على الأقل

⚠️ قاعدة ذهبية: تراجع الكود سهل، تراجع البيانات صعب. صمّم migrations على هذا الأساس.

💡 إذا أردت فريقًا يتولى التنفيذ الكامل (تطوير + نشر + تحسين + مراقبة)، ابدأ من خدمة تطوير الويب في نقطة.

الخطوة 10 — مراقبة عملية بدون تعقيد زائد

أقل مؤشرات لازم تتابعها:

• زمن الاستجابة p95
• نسبة أخطاء 5xx
• حجم طابور المهام
• استهلاك قاعدة البيانات
• معدل نجاح/فشل النشر

Stack بسيط وفعال:

• Uptime Kuma للـ availability
• Grafana + Loki للسجلات
• تنبيهات Telegram/Slack للأخطاء الحرجة

مثال log منظّم في Laravel:

Log::info('checkout_completed', [
  'order_id' => $order->id,
  'user_id' => $order->user_id,
  'total' => $order->total,
]);

السجلات المنظمة تختصر وقت التشخيص بشكل كبير.

الخطوة 11 — أخطاء منتشرة عند الفرق (وكيف تتفاداها)

1) بناء assets على سيرفر الإنتاج

• النتيجة: نشر بطيء وتعليق موارد
• الحل: البناء في CI فقط

2) عدم وجود health checks

• النتيجة: إصدار معطوب يستقبل ترافيك
• الحل: Gate قبل تحويل المرور

3) queue worker بدون إشراف

• النتيجة: مهام تتوقف بصمت
• الحل: Supervisor أو خدمة منفصلة للعمال

4) الاعتماد على state داخل الحاوية

• النتيجة: مشاكل عند التوسعة
• الحل: انقل الحالة لـ DB/Redis/Object Storage

5) لا يوجد staging

• النتيجة: الإنتاج يصبح مختبرك
• الحل: staging شبه مطابق للإنتاج

الخطوة 12 — Workflow فريق مقترح

هذا النمط مناسب لمعظم الفرق الصغيرة والمتوسطة:

1. Branch لكل مهمة
2. Pull Request مع CI إجباري
3. Merge إلى main بعد المراجعة
4. بناء image تلقائيًا
5. نشر إلى staging
6. smoke tests سريعة
7. ترقية نفس image إلى production

بهذا الشكل تقل العشوائية، ويزيد وضوح المسؤولية، ويصبح أي خلل قابلًا للتتبع.

الخلاصة

المنظومة التي بنيناها اليوم تعطيك 3 مكاسب مباشرة:

1. الاستقرار: نفس البيئة محليًا وفي الإنتاج
2. الثقة: أي تغيير يمر عبر اختبارات آلية
3. المرونة: rollback سريع بدل ساعات إطفاء حرائق

لو ستبدأ بجزء واحد فقط، ابدأ بـ CI شامل للاختبارات.
ولو ستضيف جزءًا ثانيًا، اجعل النشر مبنيًا على immutable image tags.

هذا وحده يكفي لنقل فريقك من "نشر متوتر" إلى "نشر احترافي".

مراجعة سريعة

• Docker Compose للتطوير
• Dockerfile متعدد المراحل للإنتاج
• CI متكامل على GitHub Actions
• نشر منظم عبر Coolify
• إعدادات أمان وأداء
• خطة تراجع ومراقبة

ابنِ مرة واحدة، وانشر بثقة، وكرّر بسرعة.