آموزش نصب Laravel 11 روی Ubuntu 24.04

لاراول (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 -v

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

sudo apt update
sudo apt install php php-cli php-mbstring php-xml php-mysql

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

php -v

برای 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 کاربر بروید:

cd ~

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

curl -sS https://getcomposer.org/installer | php

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

sudo mv composer.phar /usr/local/bin/composer

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

composer --version

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

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

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

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

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

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

cd /var/www

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

composer create-project --prefer-dist laravel/laravel laravel-app "11.*"

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

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

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

/var/www/laravel-app

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

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

cd /var/www/laravel-app

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

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

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

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

storage
bootstrap/cache

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

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

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

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

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

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

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

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

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

cp .env.example .env

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

php artisan key:generate

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

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

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

nano .env

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

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

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

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

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

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

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

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

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

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

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

برای مثال:

/var/www/laravel-app/public

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

/var/www/laravel-app

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

تنظیم Laravel با Apache

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

sudo a2enmod rewrite

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

sudo nano /etc/apache2/sites-available/laravel-app.conf

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

&amp;lt;VirtualHost *:80&amp;gt;
ServerName your-domain.com
DocumentRoot /var/www/laravel-app/public

&amp;lt;Directory /var/www/laravel-app/public&amp;gt;
AllowOverride All
Require all granted
&amp;lt;/Directory&amp;gt;

ErrorLog ${APACHE_LOG_DIR}/laravel-app-error.log
CustomLog ${APACHE_LOG_DIR}/laravel-app-access.log combined
&amp;lt;/VirtualHost&amp;gt;

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

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

sudo a2ensite laravel-app

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

sudo systemctl restart apache2

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

تنظیم Laravel با Nginx

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

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

sudo nano /etc/nginx/sites-available/laravel-app

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

server {
listen 80;
server_name your-domain.com;

root /var/www/laravel-app/public;

index index.php index.html index.htm;

location / {
try_files $uri $uri/ /index.php?$query_string;
}

location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}

location ~ /\.ht {
deny all;
}

error_log /var/log/nginx/laravel-app-error.log;
access_log /var/log/nginx/laravel-app-access.log;
}

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

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

ls /var/run/php/

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

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

sudo ln -s /etc/nginx/sites-available/laravel-app /etc/nginx/sites-enabled/

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

sudo nginx -t

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

sudo systemctl restart nginx

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

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

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

برای بررسی Nginx:

sudo systemctl status nginx

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

sudo systemctl status php8.3-fpm

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

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

php -v

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

composer --version

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

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

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

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

cd /var/www/laravel-app

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

php artisan migrate

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

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

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

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

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

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

sudo systemctl status 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 و مانیتورینگ سرور را به‌صورت جداگانه پیکربندی کنید.

دنبال چه می‌گردی؟

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