راهنمای کامل دیپلوی اپلیکیشن لاراول روی کوبرنتیز

کد روی لپ‌تاپ شما درست کار می‌کند، تست‌ها سبزند و حالا باید آن را وارد production کنید؛ همان نقطه‌ای که سؤال‌ها شروع می‌شوند: APP_KEY را کجا بگذاریم؟ Migration چه زمانی اجرا شود؟ فایل‌های آپلودی با حذف پاد چه می‌شوند؟

دیپلوی لاراول روی Kubernetes فقط ساختن کانتینر و اجرای kubectl apply نیست. باید وب‌اپلیکیشن، Queue Worker، تنظیمات محیط، Secretها، Probeها و فضای ذخیره‌سازی را جداگانه ببینید. مسیر این راهنما از Dockerfile شروع می‌شود و به Deployment، Service، Ingress و عیب‌یابی production می‌رسد.

پاسخ سریع: برای اجرای Laravel روی Kubernetes به چه چیزهایی نیاز دارید؟

مسیر استقرار یک اپلیکیشن معمولی این است:

1. پروژه Laravel را داخل یک Image قرار دهید.

2. Image را در Registry در دسترس کلاستر بگذارید.

3. مقادیر غیرحساس را با ConfigMap یا متغیرهای محیطی تعریف کنید.

4. APP_KEY و اطلاعات اتصال دیتابیس را در Secret نگه دارید.

5. وب‌اپلیکیشن را با Deployment اجرا کنید.

6. با Service یک آدرس ثابت داخلی بسازید.

7. ترافیک بیرونی را از Ingress به Service برسانید.

8. Migration را در یک Job جدا اجرا کنید.

9. Queue Worker و Horizon را از وب‌اپلیکیشن جدا نگه دارید.

10. برای مسیر سلامت برنامه، readinessProbe و livenessProbe تعریف کنید.

این معماری از اجرای همه اجزا داخل یک پاد طولانی‌تر است، ولی عیب‌یابی را ساده می‌کند. اگر Worker از کار افتاد، وب‌اپلیکیشن نباید همراهش Restart شود.

قبل از دیپلوی لاراول چه چیزهایی را آماده کنیم؟

نمونه‌های این راهنما بر مبنای PHP 8.3 و نسخه‌ای از Laravel نوشته شده‌اند که Health Check آن در مسیر /up فعال است. Laravel جدید این مسیر را به‌صورت پیش‌فرض دارد؛ در پروژه‌های قدیمی‌تر باید خودتان یک Health Route بسازید.

APP_ENV=production
APP_DEBUG=false
APP_URL=https://app.example.com

LOG_CHANNEL=stderr
LOG_LEVEL=warning

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=app

ابتدا تنظیمات production را مرور کنید: فایل .env واقعی را داخل Image کپی نکنید و در Git نگذارید. Kubernetes متغیرها را هنگام ساخت پاد وارد کانتینر می‌کند؛ در نتیجه می‌توانید تنظیمات staging و production را بدون قراردادن رمزها در لایه‌های Image تغییر دهید.

مقدار APP_DEBUG در production باید false باشد. روشن‌ماندن آن ممکن است Stack Trace و بخشی از تنظیمات حساس برنامه را به کاربر نشان دهد.

پیش از ادامه، این دستورها را در CI یا محیط Build اجرا کنید:

composer install \
  --no-dev \
  --prefer-dist \
  --no-interaction \
  --no-progress \
  --optimize-autoloader

php artisan optimize

دستور optimize تنظیمات، Routeها، Eventها و Viewها را Cache می‌کند. پس از اجرای config:cache، فراخوانی مستقیم env() بیرون از فایل‌های پوشه config قابل‌اعتماد نیست. در کد برنامه از config() استفاده کنید.

چگونه برای Laravel یک Image قابل‌استفاده بسازیم؟

این Dockerfile یک نمونه پایه است. اگر اپلیکیشن شما Extension دیگری مثل gd، intl یا zip می‌خواهد، آن را به مرحله Build اضافه کنید.

FROM composer:2 AS vendor

WORKDIR /app

COPY composer.json composer.lock ./

RUN composer install \
    --no-dev \
    --prefer-dist \
    --no-interaction \
    --no-progress \
    --optimize-autoloader \
    --no-scripts

COPY . .

RUN composer dump-autoload --optimize \
    && php artisan package:discover --ansi

FROM php:8.3-cli

WORKDIR /var/www/html

RUN docker-php-ext-install pdo_mysql

COPY --from=vendor /app /var/www/html

RUN chown -R www-data:www-data storage bootstrap/cache

USER www-data

EXPOSE 8000

CMD ["php", "artisan", "serve", "--host=0.0.0.0", "--port=8000"]

برای تست محلی:

docker build -t registry.example.com/team/laravel-app:1.0.0 .
docker run --rm -p 8000:8000 \
  -e APP_ENV=production \
  -e APP_DEBUG=false \
  -e APP_KEY='base64:REPLACE_WITH_REAL_KEY' \
  registry.example.com/team/laravel-app:1.0.0 

عبارت REPLACE_WITH_REAL_KEY را باید با کلید واقعی پروژه جایگزین کنید. سپس مسیر Health Check را بررسی کنید:

curl -i http://127.0.0.1:8000/up

خروجی موفق باید Status Code برابر 200 داشته باشد. محتوای Response به نسخه Laravel و تنظیمات پروژه وابسته است.

اجرای php artisan serve برای ساده‌ماندن نمونه انتخاب شده است. Runtime و وب‌سرور production را براساس تست فشار، Extensionهای پروژه و الگوی ترافیک انتخاب کنید. در محیط Production، پاستا پیشنهاد می‌کند اجزای مختلف Laravel را بر اساس مسئولیتشان از هم جدا کنید:

• Web: اجرای Laravel با PHP production و وب‌سرور مناسب، با Document Root روی public

• Database: استفاده از MySQL یا PostgreSQL مدیریت‌شده و تنظیم اتصال از طریق DATABASE_URL

• Migration: اجرای php artisan migrate --force به‌عنوان Release Command، پیش از انتقال ترافیک

• Queue: اجرای php artisan queue:work در یک Worker مستقل

• Scheduler: اجرای php artisan schedule:work یا Cron در یک Process جدا

• Secrets: نگهداری APP_KEY و سایر اطلاعات حساس در متغیرهای امن پروژه، نه داخل Git

• Storage: اتصال storage/app/public به Volume پایدار یا استفاده از S3 برای فایل‌های آپلودی

• Build: اجرای composer install --no-dev --optimize-autoloader و، در صورت استفاده از Vite، ساخت assetها با npm run build

Queue و Scheduler نباید داخل کانتینر Web اجرا شوند؛ جداسازی آن‌ها مقیاس‌دهی، تخصیص منابع و Restart هر فرایند را مستقل و قابل‌اعتماد نگه می‌دارد. همچنین APP_KEY باید فقط یک‌بار تولید شود، زیرا تغییر آن داده‌های رمز‌شده و نشست‌های قبلی را نامعتبر می‌کند.

پاستا یک پلتفرم ابری استقرار و توزیع نرم‌افزار مبتنی بر Kubernetes و OpenShift است. در PaaSta Cooker می‌توانید Build و استقرار را با تعریف گرافیکی یا مانیفست YAML انجام دهید. Paastafile نیز امکان استقرار بدون نوشتن Dockerfile را فراهم می‌کند. Namespace، Persistent Volume، Ingress، متغیر محیطی و Secret در اختیار شماست.

پاستا multi-cloud است و روی ارائه‌دهنده‌های مختلف اجرا می‌شود. اگر تیم شما می‌خواهد تمام اجزای کلاستر، Controllerها و سیاست‌های سطح پایین Kubernetes را مستقیماً مدیریت کند، PaaS لزوماً انتخاب اول نیست. مقایسه هزینه عملیاتی دو مسیر را در مطلب «PaaS یا سرور مجازی؟ کدام برای تیم شما مقرون‌به‌صرفه‌تر است» بخوانید.