К содержимому

Разработка сайта на Laravel на Ubuntu 24.04

Сайт на Laravel собирают из нового проекта, базы MySQL, панели Filament и компонентов Livewire, а наружу отдают через nginx. На Ubuntu 24.04 с PHP 8.3 весь путь занимает несколько команд, и каждую можно проверить до перехода к следующей.

Руководство Laravel 3 мин чтения

01Проверьте PHP и Composer

Laravel 13 требует PHP 8.3 и выше, и PHP 8.3 из Ubuntu 24.04 подходит. Убедитесь, что установлены CLI, FPM, расширения php8.3-mbstring, php8.3-xml, php8.3-curl, php8.3-zip, php8.3-bcmath, php8.3-intl и драйвер php8.3-mysql. Composer ставят один раз, он нужен для создания проекта и установки пакетов.

bash
php -v
composer --version
sudo apt install php8.3-cli php8.3-fpm php8.3-mbstring php8.3-xml php8.3-curl php8.3-zip php8.3-bcmath php8.3-intl php8.3-mysql

02Создайте проект Laravel

Проект создают в каталоге /var/www/example.com командой composer create-project. После установки проверьте версию фреймворка и сгенерируйте APP_KEY: без него Laravel отвечает ошибкой No application encryption key has been specified.. Ключ создают один раз, при переезде переносят вместе с .env.

bash
cd /var/www
composer create-project laravel/laravel example.com
cd example.com
php artisan --version
php artisan key:generate

03Подключите MySQL

В свежем проекте DB_CONNECTION=sqlite, а очереди и кэш уже смотрят в базу. Для сайта на MySQL создайте базу и пользователя, затем поменяйте .env: DB_CONNECTION=mysql и значения DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD. Миграции создают таблицы, включая sessions, без которой не работает драйвер сессий по умолчанию.

bash
sudo mysql -e "CREATE DATABASE example CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'example'@'localhost' IDENTIFIED BY 'secret'; GRANT ALL ON example.* TO 'example'@'localhost';"
php artisan migrate

04Настройте nginx на каталог public

Для Laravel root в nginx смотрит в /var/www/example.com/public, поэтому .env и код вне public наружу не отдаются. Отдельный location для .js с try_files $uri =404; ломает скрипт Livewire по адресу /livewire-<хеш>/livewire.min.js, и компоненты перестают реагировать. В таком location запрос отдают в index.php.

nginx
server {
    listen 80;
    server_name example.com;
    root /var/www/example.com/public;
    index index.php;

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

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }
}

05Поставьте Filament и создайте пользователя

Filament 5 строит админку на Livewire и требует PHP 8.2 и выше. Пакет ставят через Composer, а php artisan filament:install --panels создаёт app/Providers/Filament/AdminPanelProvider.php и открывает панель по адресу /admin. Пользователя для входа создаёт php artisan make:filament-user.

bash
composer require filament/filament:"^5.0"
php artisan filament:install --panels
php artisan make:filament-user

06Разрешите вход в панель на сервере

Без интерфейса Filament\Models\Contracts\FilamentUser в модели User Filament пускает в панель только при APP_ENV=local. На сервере с APP_ENV=production вход заканчивается ошибкой 403. Добавьте интерфейс и метод canAccessPanel, который пускает нужных пользователей.

php
<?php

namespace App\Models;

use Filament\Models\Contracts\FilamentUser;
use Filament\Panel;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements FilamentUser
{
    public function canAccessPanel(Panel $panel): bool
    {
        return $this->email === 'admin@example.com';
    }
}

07Создайте ресурс для данных сайта

Ресурс Filament даёт таблицу и форму для модели. Команда php artisan make:filament-resource Customer создаёт ресурс для модели Customer, и после миграций записи можно добавлять и править прямо в панели. После деплоя запускают php artisan filament:optimize, он кэширует компоненты и Blade-иконки Filament.

bash
php artisan make:model Customer -m
php artisan migrate
php artisan make:filament-resource Customer
php artisan filament:optimize

08Добавьте компонент Livewire

Livewire 4 ставится через Composer, а php artisan make:livewire counter по умолчанию создаёт однофайловый компонент. С ключом --mfc получается компонент из нескольких файлов. Скрипт Livewire отдаёт сам Laravel по адресу вида /livewire-<хеш>/livewire.min.js, и хеш зависит от APP_KEY.

bash
composer require livewire/livewire
php artisan make:livewire counter

Частые ошибки

  • Вход в /admin на сервере заканчивается ошибкой 403 Forbidden.

    Модель User не реализует Filament\Models\Contracts\FilamentUser, а APP_ENV не local. Добавьте интерфейс и метод canAccessPanel(Panel $panel): bool, который пускает нужных пользователей.

  • Компоненты Livewire не реагируют, в консоли браузера 404 на livewire.min.js.

    Адрес /livewire-<хеш>/livewire.min.js перехватил location nginx для статических .js с try_files $uri =404;. Отдайте такой location в index.php: try_files $uri /index.php?$query_string;, затем выполните sudo nginx -t и sudo systemctl reload nginx.

  • composer install и php artisan optimize падают с Permission denied после смены владельца каталогов.

    Каталоги storage и bootstrap/cache отдали целиком www-data. Верните владельцем пользователя, который деплоит: sudo chown -R $USER:www-data storage bootstrap/cache, и запускайте команды без sudo.

  • После правки .env сайт работает со старыми значениями.

    Конфиг закэширован командой php artisan optimize. Выполните php artisan config:clear или php artisan optimize заново.

Deploykin

Как это делается в Deploykin

В Deploykin сайт на Laravel создаётся из панели: стек под приложение, key:generate и storage:link выполняются при создании, а доступы к базе сами попадают в .env. Деплой идёт без простоя, с миграциями и кэшами, а очереди держат демоны Horizon или Queue Worker.

7 дней бесплатно на тарифе Про, без привязки карты.

Вопросы и ответы

Какая версия PHP нужна для Laravel 13 на Ubuntu 24.04?

Laravel 13 требует PHP 8.3 и выше, и PHP 8.3 из Ubuntu 24.04 подходит. Нужны расширения php8.3-mbstring, php8.3-xml, php8.3-curl, php8.3-zip, php8.3-bcmath, php8.3-intl и php8.3-mysql.

Чем заменить app/Http/Kernel.php в Laravel 13?

Файла app/Http/Kernel.php с Laravel 11 нет. Middleware, маршруты и обработку исключений настраивают в bootstrap/app.php.

Почему Filament не пускает в панель на рабочем сервере?

Вне APP_ENV=local Filament пускает только пользователей, которых пропускает canAccessPanel из интерфейса FilamentUser. Без этого метода вход заканчивается ошибкой 403.

Как добавить API к сайту на Laravel?

Команда php artisan install:api ставит Laravel Sanctum 4 и подключает routes/api.php в bootstrap/app.php. Защищённые маршруты API закрывает middleware auth:sanctum.

Что делать, если после деплоя на сайте ошибка 500?

Laravel пишет ошибку в storage/logs/laravel.log. При APP_DEBUG=false в браузере видна только общая страница, поэтому причину смотрят в логе.

Ещё по теме

Laravel: руководство по установке и настройке: все материалы темы

Мы используем cookies и сервис веб-аналитики «Яндекс Метрика» (включая Вебвизор) для улучшения работы сайта. Подробности — в политике конфиденциальности.