Laravel/envoy

مقدمة

يوفّر Laravel Envoy صياغة نظيفة ومختزلة لتعريف المهام الشائعة وتشغيلها على الخوادم البعيدة (remote servers)، ويمكنك إعداد المهام بسهولة باستخدام صياغة نمط Blade للنشر، أوامر Artisan وغيرها. ويدعم Envoy في الوقت الحالي أنظمة تشغيل لينكس و ماك فقط.

التثبيت

ثبّت أولًا Envoy باستخدام أمر global require الخاص بالأمر Composer:

composer global require laravel/envoy

قد تتسبب مكتبات Composer العامة (global) في بعض الأحيان في حدوث تعارضات في الحزم، يمكنك في هذه الحالة استخدام مكتبة cgr والذي يعد بديلًا للأمر composer global require ويمكنك العثور على تعليمات تثبيت مكتبة cgr في GitHub.

تنبيه: تأكد من وضع مسار مجلد ‎~/.composer/vendor/bin في متغير البيئة PATH الخاص بك حتى يُعثر على Envoy عند تشغيل أمر envoy في طرفيتك.

تحديث Envoy

يمكنك أيضًا استخدام Composer لإبقاء آخر نسخة محدّثة من Envoy، فبتشغيل الأمر composer global update ستتحدث جميع حزم Composer العامة (Global):

composer global update

كتابة المهام

يجب تعريف جميع مهام Envoy في ملف Envoy.blade.php في جذر مشروعك، وهذا مثال على ذلك للبدء:

@servers(['web' => ['user@192.168.1.1']])
@task('foo', ['on' => 'web'])
   ls -la
@endtask

فكما ترى، مصفوفة من ‎@servers معرّفة في أعلى الملف للسماح لك بالإشارة إلى هذه الخوادم في خيار on من تعريف المهام، ويجب عليك وضع شيفرة Bash في داخل تعريفات ‎@task التي يجب أن تعمل على خادمك عند تنفيذ المهمة. يمكنك إجبار السكربت على العمل محليًا عن طريق تحديد 127.0.0.1 كعنوان IP للخادم:

@servers(['localhost' => '127.0.0.1'])

الإعداد

قد تحتاج في بعض الأحيان إلى تنفيذ بعض شيفرات PHP قبل تنفيذ مهام Envoy، يمكنك استخدام موجه ‎@setup للإعلان عن المتغيرات وعمل أعمال PHP العامة قبل تنفيذ أي من مهامك الأخرى:

@setup
   $now = new DateTime();
   $environment = isset($env) ? $env : "testing";
@endsetup

إذا أردت استدعاء ملفات PHP أخرى قبل تنفيذ المهمة، يمكنك استخدام موجه ‎@include في أعلى ملف Envoy.blade.php:

@include('vendor/autoload.php')
@task('foo')
  # ...
@endtask

المتغيرات

يمكنك تمرير قيم الخيار إلى مهام Envoy إذا لزم الأمر باستخدام سطر الأوامر:

envoy run deploy --branch=master

يمكنك الوصول إلى مهامك عن طريق صياغة "echo" الخاصة بـ Blade، ويمكنك بالطبع استخدام if وحلقات التكرار داخل مهامك، فعلى سبيل المثال، دعنا نتحقق من وجود متغيّر ‎$branch قبل تنفيذ أمر git pull:

@servers(['web' => '192.168.1.1'])

@task('deploy', ['on' => 'web'])
    cd site

    @if ($branch)
        git pull origin {{ $branch }}
    @endif

    php artisan migrate
@endtask

  القصص Stories

القصص هي مجموعة من المهام تحت اسم واحد مناسب، مما يسمح لك بتجميع المهام الصغيرة والمركّزة في مهام كبيرة. على سبيل المثال، يمكن لقصة deploy أن تشغل مهام git و composer من خلال سرد أسماء المهام داخل تعريفها:

@servers(['web' => '192.168.1.1'])

@story('deploy')
    git
    composer
@endstory

@task('git')
    git pull origin master
@endtask

@task('composer')
    composer install
@endtask

وبمجرد كتابة القصة، يمكنك تشغيلها مثل المهمة النموذجيّة:

envoy run deploy

خوادم متعددة

يسمح لك Envoy بتشغيل مهمة عبر العديد من الخوادم بسهولة، أضف أولًا الخوادم الإضافيّة إلى إعلان ‎@servers الخاص بك، ويجب عليك تعيين اسم فريد لكل خادم، وبمجرد تحديد خوادمك الإضافيّة، ضع كل خوادمك في مصفوفة المهمة (task on):

@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])

@task('deploy', ['on' => ['web-1', 'web-2']])
    cd site
    git pull origin {{ $branch }}
    php artisan migrate
@endtask

التنفيذ التفرّعي

بشكل افتراضي، ستُنفذ المهام على كل خادم بشكل تسلسلي، وبمعنى آخر، سينتهي تنفيذ المهمة على الخادم الأول قبل المتابعة في الخادم الثاني، وإذا كنت ترغب في تشغيل مَهمَة عن طريق عدة خوادم بالتوازي، فأضف خيار parallel لتصريح أفضل:

@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])

@task('deploy', ['on' => ['web-1', 'web-2'], 'parallel' => true])
    cd site
    git pull origin {{ $branch }}
    php artisan migrate
@endtask

تشغيل المهام

لتشغيل مهمة أو قصة معرّفة في ملف Envoy.blade.php، نفّذ أمر run الخاص بـ Envoy، ومرّر اسم المهمة أو القصة التي ترغب في تنفيذها، وسيُشغّل Envoy المهمة وسيعرض المخرجات من الخوادم أثناء تشغيل المهمة:

envoy run task

تأكيد تنفيذ المهمة

إذا كنت ترغب في أن تحصل على تأكيد قبل تشغيل مهمة معينة على خوادمك الخاصة، فيجب عليك إضافة توجيه confirm إلى إعلان المهمة، وهذا الخيار مفيد للعمليات المدمرة:

@task('deploy', ['on' => 'web', 'confirm' => true])
    cd site
    git pull origin {{ $branch }}
    php artisan migrate
@endtask

الإشعارات

Slack

يدعم Envoy إرسال الإشعارات إلى Slack بعد تنفيذ كل مهمة، يقبل موجه ‎@slack عنوان خطّاف URL واسم القناة، ويمكنك الحصول على عنوان خطّاف ‎(webhook) URL عن طريق إنشاء تكامل "Incoming WebHooks" في لوحة تحكم Slack، ويجب عليك تمرير كامل عنوان webhook URL إلى موجه ‎@slack:

@finished
    @slack('webhook-url', '#bots')
@endfinished

يمكنك توفير أي مما يلي كمعامل القناة:

• لإرسال التنبيهات إلى قناة: ‎#channel.

• لإرسال التنبيهات إلى مستخدم: ‎@user.

مصادر

• صفحة مشغّل المهام Envoy في توثيق Laravel الرسمي.