راهنمای کامل راه‌اندازی لاراول روی سرور لینوکس

• ۱۵ مهر ۱۴۰۵
• دسته بندی ها: سرور, لینوکس

لاراول (Laravel) یکی از محبوبترین فریم‌ورک‌های PHP برای توسعه برنامه‌های وب است که امکانات متنوعی برای ساخت وب‌سایت‌ها، پنل‌های مدیریتی، APIها و برنامه‌های تحت وب در اختیار توسعه‌دهندگان قرار می‌دهد. استفاده از Laravel در کنار Ubuntu 24.04 می‌تواند یک محیط پایدار و مناسب برای توسعه و اجرای پروژه‌های PHP ایجاد کند.

در این مطلب، مراحل نصب Laravel 11 روی Ubuntu 24.04 را از ابتدا بررسی می‌کنیم. اول وضعیت PHP را بررسی کرده و در صورت نیاز افزونه‌های موردنیاز را نصب می‌کنیم. سپس Composer را راه‌اندازی کرده و با استفاده از آن یک پروژه Laravel 11 ایجاد می‌کنیم.

در ادامه، دسترسی‌های لازم برای دایرکتوری‌های لاراول را تنظیم می‌کنیم، فایل محیطی env. را ایجاد کرده و کلید برنامه را می‌سازیم. در نهایت نحوه پیکربندی Apache یا Nginx برای اجرای پروژه Laravel و اجرای Migrationهای پایگاه داده را توضیح خواهیم داد.

 Laravel 11 حداقل به PHP 8.2 نیاز دارد و افزونه‌هایی مانند Ctype، cURL، DOM، Fileinfo، Mbstring، OpenSSL، PDO، Session، Tokenizer و XML برای اجرای صحیح فریمورک موردنیاز هستند.

پیش‌نیازهای نصب Laravel 11 روی Ubuntu 24.04

قبل از شروع نصب Laravel، باید سرور Ubuntu 24.04 آماده باشد و دسترسی SSH یا دسترسی مدیریتی به سرور داشته باشید.

برای اجرای Laravel به PHP، Composer و وب‌سروری مانند Nginx یا Apache نیاز دارید. اگر پروژه شما از  MySQL استفاده می‌کند، افزونه PHP مربوط به MySQL باید روی سرور نصب باشد.

اولین مرحله، بررسی نسخه PHP نصب‌شده است:

اگر PHP روی سرور نصب نباشد، می‌توانید بسته‌های موردنیاز را با دستور زیر نصب کنید:

پس از نصب، دوباره نسخه PHP را بررسی کنید:

برای Laravel 11 بهتر است PHP 8.2 یا نسخه‌های جدیدتر مورد استفاده قرار گیرد. مستندات Laravel 11 حداقل نسخه PHP 8.2 را مشخص کرده‌اند.

در یک سرور واقعی، علاوه بر PHP CLI، معمولا PHP-FPM هم برای اتصال PHP به Nginx یا Apache موردنیاز است. همچنین بسته‌های دیگری مانند php-curl و php-zip بسته به نیاز پروژه می‌توانند ضروری باشند.

مرحله اول، نصب Composer روی Ubuntu 24.04

Composer ابزار مدیریت وابستگی‌های PHP است و Laravel برای نصب پکیج‌ها و ایجاد پروژه از آن استفاده می‌کند.

بدون Composer مدیریت وابستگی‌های لاراول و بسیاری از کتابخانه‌های موردنیاز پروژه دشوار خواهد بود. به همین دلیل، قبل از ایجاد پروژه Laravel باید Composer را روی سرور نصب کنیم.

ابتدا به دایرکتوری Home کاربر بروید:

سپس نصب‌کننده Composer را دریافت و اجرا کنید:

بعد از اجرای موفق دستور، فایل composer.phar ایجاد می‌شود. برای اینکه بتوانید Composer را از هر مسیری اجرا کنید، آن را به مسیر usr/local/bin/ منتقل کنید:

اکنون باید نصب Composer را بررسی کنید:

اگر نصب به‌درستی انجام شده باشد، نسخه Composer در خروجی نمایش داده می‌شود.

Composer برای نصب وابستگی‌های لاراول و ایجاد پروژه استفاده می‌شود. در مستندات فعلی هم Composer به‌عنوان یکی از ابزارهای اصلی موردنیاز برای ایجاد برنامه Laravel معرفی شده است.

مرحله دوم، نصب Laravel 11 با Composer

پس از نصب PHP و Composer، می‌توانیم پروژه Laravel 11 را ایجاد کنیم.

برای نمونه، پروژه را در مسیر var/www/ قرار می‌دهیم. این مسیر یکی از مسیرهای رایج برای نگهداری برنامه‌های وب روی سرورهای لینوکس است.

ابتدا وارد مسیر موردنظر شوید:

سپس با Composer پروژه Laravel 11 را ایجاد کنید:

در این دستور، بخش laravel/laravel بسته اصلی Laravel است و عبارت laravel-app نام پوشه پروژه خواهد بود.

استفاده از “11.*” باعث می‌شود پروژه از شاخه نسخه 11 Laravel ایجاد شود.

پس از اجرای موفق دستور، ساختار پروژه در مسیر زیر قرار خواهد گرفت:

در این مرحله Composer تمام وابستگی‌های موردنیاز Laravel را دریافت و نصب می‌کند. مدت زمان انجام این عملیات به سرعت اینترنت و منابع سرور بستگی دارد.

برای بررسی فایل‌های پروژه می‌توانید وارد پوشه آن شوید:

Laravel توصیه می‌کند برنامه از دایرکتوری public سرو شود و نباید ریشه کل پروژه مستقیم در معرض وب قرار گیرد. این موضوع برای جلوگیری از دسترسی عمومی به فایل‌های حساس پروژه اهمیت زیادی دارد.

مرحله سوم، تنظیم دسترسی‌های Laravel

Laravel برای ذخیره فایل‌های موقت، لاگ‌ها، Cache و برخی داده‌های قابل نوشتن به دسترسی مناسب نیاز دارد.

دو مسیر مهم در این زمینه عبارتند از:

در روش پیشنهادی منبع اصلی، مالکیت این دو مسیر به کاربر وب‌سرور www-data اختصاص داده می‌شود:

اگر از Nginx و PHP-FPM با کاربر www-data استفاده می‌کنید، این تنظیم می‌تواند برای اجرای صحیح Laravel مناسب باشد.

با این حال، در محیط‌های پروداکشن بهتر است دسترسی‌ها با دقت تنظیم شوند و از دادن دسترسی نوشتن غیرضروری به کل پروژه خودداری شود.

نباید برای حل مشکلات پرمیشن به‌صورت غیرضروری از دسترسی‌های بسیار باز مانند 777 استفاده کنید. چنین تنظیمی می‌تواند سطح امنیت سرور را کاهش دهد.

مرحله چهارم، ایجاد و تنظیم فایل env.

لاراول برای نگهداری تنظیمات محیط اجرا از فایل env. استفاده می‌کند.

این فایل می‌تواند شامل تنظیمات مربوط به محیط اجرا، کلید برنامه، پایگاه داده، Cache و سرویس‌های مختلف باشد.

ابتدا از فایل نمونه .env.example یک فایل env. ایجاد کنید:

سپس کلید امنیتی Laravel را ایجاد کنید:

در صورت موفقیت، Laravel یک APP_KEY جدید ایجاد کرده و آن را در فایل env. قرار می‌دهد.

این کلید برای برخی قابلیت‌های رمزنگاری Laravel ضروری است و نباید آن را به‌صورت عمومی منتشر کنید.

برای ویرایش فایل محیطی می‌توانید از ویرایشگر Nano استفاده کنید:

تنظیم اتصال Laravel به MySQL

اگر پایگاه داده پروژه شما MySQL است، اطلاعات اتصال باید در فایل env. مشخص شود.

نمونه تنظیمات به شکل زیر است:

مقادیر DB_DATABASE، DB_USERNAME و DB_PASSWORD را باید بر اساس پایگاه داده و کاربر ایجادشده روی سرور تغییر دهید.

بهتر است برای پروژه Laravel یک کاربر اختصاصی دیتابیس ایجاد کنید و از استفاده از حساب مدیریتی مانند root برای برنامه در محیط پروداکشن خودداری کنید.

همچنین فایل env. نباید از طریق وب قابل دسترسی باشد. به همین دلیل، تنظیم صحیح Document Root وب‌سرور اهمیت زیادی دارد.

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

مرحله پنجم، تنظیم وب‌سرور برای Laravel

پس از نصب Laravel، پروژه باید توسط یک وب‌سرور مانند Apache یا Nginx ارائه شود.

یکی از مهمترین نکات در این مرحله، تنظیم Document Root روی دایرکتوری public پروژه است.

برای مثال:

نباید Document Root را روی مسیر زیر قرار دهید:

زیرا در این حالت احتمال افشای فایل‌های حساس پروژه افزایش پیدا می‌کند. مستندات لاراول هم تاکید می‌کنند که برنامه باید از دایرکتوری public سرو شود.

تنظیم Laravel با Apache

اگر روی سرور از Apache استفاده می‌کنید، ابتدا باید ماژول Rewrite را فعال کنید:

سپس فایل Virtual Host مربوط به پروژه را ایجاد کنید:

محتوای زیر را در فایل قرار دهید:

در این تنظیم، مقدار your-domain.com را با دامنه واقعی خود جایگزین کنید.

پس از ایجاد Virtual Host، آن را فعال کنید:

سپس آپاچی را ریستارت کنید:

اگر دامنه به IP سرور متصل باشد و DNS به‌درستی تنظیم شده باشد، می‌توانید دامنه را در مرورگر باز کنید.

تنظیم Laravel با Nginx

Nginx یکی از گزینه‌های رایج برای اجرای برنامه‌های Laravel در محیط عملیاتی است.

ابتدا فایل تنظیمات سایت را ایجاد کنید:

سپس پیکربندی زیر را قرار دهید:

در این نمونه، PHP-FPM نسخه 8.3 در نظر گرفته شده است. اگر نسخه PHP-FPM روی سرور شما متفاوت است، مسیر Socket را مطابق نسخه نصب‌شده تغییر دهید.

برای مثال، ابتدا می‌توانید Socket موجود را بررسی کنید:

سپس نام Socket صحیح را در مقدار fastcgi_pass قرار دهید.

پس از ایجاد فایل، یک Symbolic Link برای فعال‌کردن سایت ایجاد کنید:

قبل از ریستارت Nginx بهتر است صحت تنظیمات را بررسی کنید:

اگر خروجی نشان داد که Syntax تنظیمات صحیح است، Nginx را ریستارت نمائید:

پیکربندی Nginx باید تمام درخواست‌های برنامه را در نهایت به public/index.php منتقل کند. این روش با معماری استاندارد Laravel مطابقت دارد.

بررسی وضعیت سرویس‌های PHP و Nginx

بعد از راه‌اندازی وب‌سرور، بهتر است وضعیت سرویس‌ها را بررسی کنید.

برای بررسی Nginx:

برای بررسی PHP-FPM:

اگر از نسخه دیگری از PHP استفاده می‌کنید، نام سرویس را متناسب با همان نسخه تغییر دهید.

همچنین می‌توانید نسخه PHP را بررسی کنید:

وضعیت Composer را هم بررسی کنید:

در صورت مشاهده خطای 502 Bad Gateway در Nginx، یکی از مواردی که باید بررسی شود Socket مربوط به PHP-FPM است. اگر مسیر Socket در تنظیمات Nginx با Socket واقعی PHP-FPM یکسان نباشد، Nginx نمی‌تواند درخواست‌های PHP را پردازش کند.

مرحله ششم، اجرای Migrationهای Laravel

اگر پایگاه داده پروژه ایجاد و تنظیمات آن در فایل env. وارد شده است، می‌توانید Migrationهای Laravel را اجرا کنید.

برای این کار وارد پوشه پروژه شوید:

سپس دستور زیر را اجرا کنید:

Laravel به پایگاه داده متصل شده و Migrationهای موجود را اجرا می‌کند.

اگر اتصال به پایگاه داده صحیح باشد، جدول‌های موردنیاز ایجاد خواهند شد.

مستندات لاراول پس از تنظیم پایگاه داده، اجرای php artisan migrate را برای ایجاد جدول‌های Migration پیشنهاد می‌کنند.

در صورتی که هنگام اجرای این دستور خطایی مشاهده کردید، ابتدا اطلاعات زیر را بررسی کنید:

• نام پایگاه داده
• نام کاربری پایگاه داده
• رمز عبور
• آدرس DB_HOST
• پورت MySQL
• فعال بودن سرویس MySQL
• نصب بودن افزونه pdo_mysql

برای بررسی سرویس MySQL می‌توانید از دستور زیر استفاده کنید:

تست نهایی پروژه Laravel

پس از انجام تمام مراحل، باید بتوانید پروژه Laravel را از طریق دامنه مشاهده کنید.

برای بررسی دقیق‌تر، ابتدا مطمئن شوید دامنه به IP سرور اشاره می‌کند. سپس Nginx یا Apache، PHP-FPM و پایگاه داده را بررسی کنید.

دایرکتوری public نقطه ورود برنامه از طریق وب است و فایل index.php داخل آن درخواست‌ها را به هسته Laravel منتقل می‌کند.

قرار دادن سایر فایل‌های پروژه خارج از Document Root یکی از نکات مهم امنیتی در استقرار Laravel است.

نکات مهم برای اجرای Laravel در محیط عملیاتی

نصب Laravel پایان کار نیست. اگر پروژه قرار است روی یک سرور واقعی و برای کاربران عمومی اجرا شود، باید تنظیمات امنیتی و عملکردی بیشتری انجام شود.

یکی از مهمترین موارد، فعال‌بودن HTTPS است. پس از اتصال دامنه به سرور، بهتر است برای سایت گواهینامه SSL نصب شود و درخواست‌های HTTP به HTTPS منتقل شوند.

همچنین در محیط پروداکشن نباید حالت Debug فعال باشد. نمایش جزئیات خطا می‌تواند اطلاعات حساسی درباره مسیر فایل‌ها، تنظیمات و ساختار داخلی برنامه در اختیار کاربران قرار دهد.

تنظیمات Cache هم برای پروژه‌های Laravel اهمیت زیادی دارد. پس از آماده‌شدن پروژه می‌توان تنظیمات Configuration، Route و View را برای کاهش پردازش‌های غیرضروری Cache کرد.

در پروژه‌هایی که از Queue استفاده می‌کنند، بهتر است Workerها به‌صورت سرویس مدیریت شوند تا پس از ریستارت سرور، پردازش‌های موردنیاز دوباره به‌صورت خودکار اجرا شوند.

در کنار این موارد، تهیه بکاپ منظم از پایگاه داده و فایل‌های مهم پروژه  باید بخشی از برنامه نگهداری سرور باشد.

خطاهای رایج هنگام نصب Laravel 11 روی Ubuntu 24.04

یکی از خطاهای متداول، پایین‌بودن نسخه PHP است. اگر نسخه PHP با نیازمندی Laravel 11 سازگار نباشد، Composer ممکن است هنگام نصب وابستگی‌ها خطا ایجاد کند.

مشکل دیگر، نصب‌نبودن افزونه‌های PHP است. Laravel به مجموعه‌ای از Extensionها مانند Mbstring، XML، Ctype، cURL، Fileinfo، OpenSSL و PDO نیاز دارد.

خطای پرمیشن هم معمولا زمانی اتفاق می‌افتد که PHP-FPM نتواند در مسیرهای storage یا bootstrap/cache بنویسد.

در Nginx اشتباه در مسیر PHP-FPM Socket می‌تواند باعث ایجاد خطای 502 Bad Gateway شود.

اگر صفحه Laravel باز نمی‌شود، بررسی لاگ‌ها یکی از بهترین روش‌ها برای پیدا کردن مشکل است. لاگ Nginx و لاگ Laravel را بررسی کنید تا مشخص شود خطا در سطح وب‌سرور، PHP یا خود برنامه رخ داده است.

جمع‌بندی

نصب Laravel 11 روی Ubuntu 24.04 فرایند پیچیده‌ای نیست، اما تنظیم صحیح PHP، Composer، دسترسی‌های فایل، فایل env. و وب‌سرور اهمیت زیادی دارد.

در این مطلب ابتدا وضعیت PHP را بررسی کردیم و Composer را نصب کردیم. سپس با استفاده از Composer یک پروژه Laravel 11 ایجاد کردیم و دسترسی‌های لازم برای مسیرهای storage و bootstrap/cache را تنظیم کردیم.

در مرحله بعد، فایل env. را ایجاد کردیم و با اجرای php artisan key:generate کلید برنامه را ساختیم. سپس نحوه اتصال Laravel به MySQL و پیکربندی Apache و Nginx را بررسی کردیم.

در نهایت با اجرای Migrationهای Laravel، پایگاه داده را آماده کردیم.

اگر این مراحل را روی یک سرور Ubuntu 24.04 انجام دهید، می‌توانید یک محیط مناسب برای اجرای برنامه Laravel 11 داشته باشید. برای محیط پروداکشن توصیه می‌شود پس از نصب اولیه، مواردی مانند HTTPS، امنیت فایل‌ها، تنظیمات PHP-FPM، Cache، Queue، Backup و مانیتورینگ سرور را به‌صورت جداگانه پیکربندی کنید.